Listings APIListings API
Iniciar sesión

Python SDK

Cliente oficial de Python para Listings API con recursos tipados, paginación por cursor, reintentos automáticos y errores con nombre.

El paquete listingsapi es el cliente oficial de Python para Listings API. Encapsula la capa REST con clases de recursos tipadas, paginación basada en cursores, reintentos automáticos ante errores transitorios y una excepción específica para cada tipo de fallo, incluidos los cuerpos de error que la plataforma devuelve con HTTP 200.

Instalación

bash
pip install listingsapi

Requiere Python 3.9 o posterior. La única dependencia en tiempo de ejecución es requests.

Autenticación

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

Obtén tu clave de API en Claves de API → Nueva clave en el panel de desarrolladores de Listings API.

El cliente acepta tres argumentos opcionales por nombre:

OpciónValor predeterminadoDescripción
base_urlhttps://listingsapi.comHost de la API al que se envían las solicitudes
timeout240.0Tiempo de espera por solicitud en segundos
max_retries2Reintentos automáticos ante respuestas 429 y 5xx, respetando Retry-After

Consulta Configuración para obtener más detalles.

Ejemplo rápido

list_locations.py
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 es una propiedad del cliente:

PropiedadQué gestiona
client.locationsUbicaciones de empresas: consulta de listas, búsqueda, creación en una sola llamada, actualización y archivado
client.reviewsReseñas y respuestas, además de análisis en client.reviews.analytics
client.postsPublicaciones de anuncios, eventos y ofertas en Google y Facebook
client.socialMarcas de Social, cuentas de redes sociales conectadas y publicaciones en Facebook, Instagram, X, LinkedIn y Pinterest
client.listingsFichas prémium y en servicios de voz, duplicados, conexión y desconexión
client.analyticsEstadísticas de perfiles de Google, Bing y Facebook
client.photosFotos de ubicaciones: carga, eliminación y marcado como favoritas
client.connected_accountsConexiones OAuth con Google y Facebook
client.workflowsAutomatizaciones predefinidas: respuesta automática a reseñas, informe de reputación y auditoría del estado de las fichas

El propio cliente incluye cuatro métodos auxiliares:

Python
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

Paginación

Los métodos que devuelven listas usan paginación basada en cursores. Cada método con paginación devuelve un objeto SyncPage: iterable, con .has_more, .next_page(), .auto_paging_iter() y .total.

Python
# 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 respuesta

Todos los métodos devuelven APIObject (acceso mediante atributos y como dict) o SyncPage (iterable, con paginación). APIObject también admite .get() y .to_dict().

Python
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()

Gestión de errores

Todos los errores del SDK heredan de listingsapi.ListingsAPIError. Los fallos de la API generan APIError o una de sus subclases: AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (con .retry_after) y InternalServerError. Los fallos de red generan APIConnectionError.

APIError contiene status_code, code (el primer código de error de la plataforma, e.g. SY10005), errors (cada entrada normalizada como diccionarios {"code", "message", "context"}) y response_body.

La plataforma comunica algunos fallos en el cuerpo de una respuesta HTTP 200: datos errors[] en el nivel superior (los tokens no válidos se devuelven como SY90005) y respuestas de escritura con success=false. El SDK también genera excepciones en esos casos, por lo que nunca tienes que comprobar los indicadores success por tu cuenta.

Python
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"])

Consulta Gestión de errores para ver la jerarquía completa de excepciones.

Siguientes pasos