Listings APIListings API
Iniciar sesión

Configuración

Configura el cliente Python de Listings API: clave de API, URL base, tiempo de espera, reintentos y registro de eventos.

Firma del constructor

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

Todos los argumentos son opcionales. Si se omite api_key, el cliente lee LISTINGSAPI_KEY del entorno y lanza AuthenticationError al crear la instancia si ninguno de los dos está definido.

Opciones

OpciónTipoValor predeterminadoDescripción
api_keystr | NoneNoneClave de API. Si no se proporciona, se usa la variable de entorno LISTINGSAPI_KEY.
base_urlstr | Nonehttps://listingsapi.comOrigen de la API. La barra final se elimina automáticamente.
timeoutfloat240.0Tiempo de espera por solicitud en segundos (se aplica a cada solicitud HTTP de forma individual).
max_retriesint2Reintentos automáticos ante respuestas 429 y 5xx. Establece el valor en 0 para desactivarlos.

Clave 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")

Tiempo de espera

El valor predeterminado es de 240.0 segundos. Para scripts de corta duración o uso interactivo, puede convenirte un valor menor:

Python
client = listingsapi.ListingsAPI(timeout=30.0)

El tiempo de espera se aplica a cada solicitud HTTP de forma individual. Las llamadas de paginación masiva (auto_paging_iter) respetan el tiempo de espera de cada solicitud de forma independiente.

Reintentos

El SDK monta un adaptador urllib3 Retry en su sesión requests que reintenta automáticamente las solicitudes que reciben respuestas 429, 500, 502, 503 y 504, pero solo para los métodos seguros: GET, HEAD y OPTIONS. Las operaciones de escritura (POST, DELETE) se envían exactamente una vez y, si fallan, lanzan una excepción de inmediato. El valor predeterminado es de 2 reintentos con un factor de espera exponencial de 0,5 segundos. Se respetan las cabeceras Retry-After, por lo que una solicitud que recibe un 429 que indica un tiempo de espera se reintenta una vez transcurrido exactamente ese tiempo.

La API v4 no admite Idempotency-Key ni detecta escrituras repetidas, por lo que una escritura que agota el tiempo de espera o devuelve un 5xx puede haberse confirmado ya. Reintentarla sin comprobarlo crearía una segunda ubicación, publicación o respuesta a una reseña. Vuelve a consultar el registro mediante una clave que controles antes de repetir una escritura.

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)

Un 429 que persiste tras todos los reintentos se lanza como RateLimitError; consulta Gestión de errores para ver cómo implementar manualmente una espera progresiva entre reintentos.

Sustitución de la URL base

Útil para entornos de preproducción o proxies internos:

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

La barra final se elimina automáticamente. Todas las solicitudes se realizan bajo la ruta /api/v4/ de este origen.

Registro de actividad

El SDK registra la actividad mediante el módulo estándar logging con el registrador listingsapi. En el nivel DEBUG, registra el método y la URL de cada solicitud (y los parámetros de consulta para GET); los cuerpos de las solicitudes y tu clave de API nunca se registran.

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

Siguientes pasos