Python SDK

Cliente oficial em Python para a Listings API com recursos tipados, paginação por cursor, novas tentativas automáticas e erros nomeados.

O pacote listingsapi é o cliente Python oficial da Listings API. Ele encapsula a camada REST com classes de recursos tipadas, paginação baseada em cursor, novas tentativas automáticas em caso de erros transitórios e uma exceção nomeada para cada tipo de falha, incluindo payloads de erro que a plataforma retorna com HTTP 200.

Instalação

pip install listingsapi

Requer Python 3.9 ou posterior. A única dependência em tempo de execução é requests.

Autenticação

import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Obtenha sua chave de API em API Keys → New key no painel de desenvolvedores da Listings API.

O cliente aceita três argumentos nomeados opcionais:

Consulte Configuração para obter detalhes.

Exemplo rápido

import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, loc.city) print(f"has_more: {page.has_more}")

Recursos

Cada recurso é uma propriedade do cliente:

Quatro métodos auxiliares estão no próprio cliente:

client.plan_sites()       # directories included in your planclient.subcategories()    # business categories (IDs for locations.add)client.countries()        # supported countries and states (ISO codes)client.subscriptions()    # active subscriptions for the account

Paginação

Os métodos que retornam listas usam paginação baseada em cursor. Cada método paginado retorna um SyncPage: iterável, com .has_more, .next_page(), .auto_paging_iter() e .total.

# Fetch one pagepage = client.locations.list(first=25)for loc in page:  print(loc.name) # Check if more pages existif page.has_more:  next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

Objetos de resposta

Todos os métodos retornam APIObject (acesso por atributo e por dict) ou SyncPage (iterável, paginado). APIObject também oferece suporte a .get() e .to_dict().

loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()

Tratamento de erros

Todos os erros do SDK derivam de listingsapi.ListingsAPIError. As falhas da API lançam APIError ou uma de suas subclasses: AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (com .retry_after) e InternalServerError. As falhas de rede lançam APIConnectionError.

APIError contém status_code, code (o primeiro código de erro da plataforma, e.g. SY10005), errors (cada entrada normalizada em dicts {"code", "message", "context"}) e response_body.

A plataforma informa algumas falhas no corpo de uma resposta HTTP 200: payloads errors[] no nível superior (tokens inválidos são retornados como SY90005) e respostas de operações de escrita com success=false. O SDK também lança exceções nesses casos, para que você nunca precise inspecionar os indicadores success por conta própria.

import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.retrieve(999999)except listingsapi.NotFoundError:  print("No such location")except listingsapi.RateLimitError as e:  print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e:  print(e.status_code, e.code)  for err in e.errors:      print(err["code"], err["message"])

Consulte Tratamento de erros para ver a hierarquia completa de exceções.

Próximos passos

• Instalação: ambientes virtuais, fixação de versões
• Início rápido: primeiras chamadas, criar um local, responder a uma avaliação
• Configuração: tempos limite, novas tentativas, URL base
• Casos de uso: exemplos completos
• Locais, Avaliações, Listagens, Análises