Listings APIListings API
Entrar

Configuração

Configure o cliente Python da Listings API: chave de API, URL base, tempo limite, novas tentativas e registro de logs.

Assinatura do construtor

Python
listingsapi.ListingsAPI(    api_key: str | None = None,    *,    base_url: str | None = None,    timeout: float = 240.0,    max_retries: int = 2,)

Todos os argumentos são opcionais. Se api_key for omitido, o cliente lê LISTINGSAPI_KEY do ambiente e lança AuthenticationError durante a construção se nenhum dos dois estiver definido.

Opções

OpçãoTipoPadrãoDescrição
api_keystr | NoneNoneChave de API. Usa a variável de ambiente LISTINGSAPI_KEY se a chave não for informada.
base_urlstr | Nonehttps://listingsapi.comOrigem da API. Uma barra no final é removida automaticamente.
timeoutfloat240.0Tempo limite por requisição, em segundos (aplica-se a cada requisição HTTP individualmente).
max_retriesint2Novas tentativas automáticas para respostas 429 e 5xx. Defina como 0 para desativar.

Chave de API

bash
export LISTINGSAPI_KEY="your-api-key"
Python
import listingsapi # From environment (recommended)client = listingsapi.ListingsAPI() # Explicit keyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Tempo limite

O padrão é 240.0 segundos. Para scripts de curta duração ou uso interativo, você pode preferir um valor menor:

Python
client = listingsapi.ListingsAPI(timeout=30.0)

O tempo limite se aplica a cada requisição HTTP individual. As chamadas de paginação em lote (auto_paging_iter) respeitam o tempo limite de cada requisição de forma independente.

Novas tentativas

O SDK configura um adaptador urllib3 Retry em sua sessão requests que repete automaticamente as requisições com respostas 429, 500, 502, 503 e 504, mas apenas para os métodos seguros: GET, HEAD e OPTIONS. As operações de escrita (POST, DELETE) são enviadas exatamente uma vez e lançam a falha imediatamente. O padrão é de 2 novas tentativas com um fator de espera exponencial de 0.5 segundo. Os cabeçalhos Retry-After são respeitados, portanto, quando um 429 especifica um tempo de espera, a requisição é repetida após exatamente esse intervalo.

A API v4 não oferece suporte a Idempotency-Key e não detecta operações de escrita repetidas, portanto, uma operação de escrita que excede o tempo limite ou retorna 5xx pode já ter sido efetivada. Repeti-la sem verificar criaria um segundo local, uma segunda publicação ou uma segunda resposta à avaliação. Consulte o registro usando uma chave que você controla antes de repetir uma operação de escrita.

Python
# More aggressive retry for long-running batch jobsclient = listingsapi.ListingsAPI(max_retries=5) # Disable retries entirely (e.g. when you want fast failures)client = listingsapi.ListingsAPI(max_retries=0)

Uma resposta 429 que persiste após todas as novas tentativas é lançada como RateLimitError; consulte Tratamento de erros para ver como implementar manualmente a espera entre tentativas.

Substituição da URL base

Útil para ambientes de homologação ou proxies internos:

Python
client = listingsapi.ListingsAPI(base_url="https://staging.example.com")

A barra no final é removida automaticamente. Todas as requisições são feitas sob o caminho /api/v4/ nessa origem.

Registro de logs

O SDK registra logs por meio do módulo padrão logging, usando o logger listingsapi. No nível DEBUG, ele registra o método e a URL de cada requisição (e os parâmetros de consulta para GET); os corpos das requisições e sua chave de API nunca são registrados.

Python
import logginglogging.basicConfig()logging.getLogger("listingsapi").setLevel(logging.DEBUG) import listingsapiclient = listingsapi.ListingsAPI()client.locations.list(first=1)

Próximos passos