Listings APIListings API
Iniciar sesión

Inicio rápido

Conéctate a Listings API, obtén la lista de tus ubicaciones, crea una con una sola llamada y responde a una reseña.

1. Configura tu clave de API

Obtén tu clave en Claves de API → Nueva clave en el panel para desarrolladores de Listings API. El SDK la lee automáticamente de la variable de entorno LISTINGSAPI_KEY.

bash
export LISTINGSAPI_KEY="your-api-key"

2. Enumera tus ubicaciones

quickstart.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, "--", loc.city, loc.stateIso) print(f"\nShowing {len(page)} locations, has_more={page.has_more}")
bash
python quickstart.py

Salida esperada:

bash
Acme Dental Downtown -- New York NYAcme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NY Showing 3 locations, has_more=False

Para solicitar todas las páginas automáticamente, usa client.locations.list(first=100).auto_paging_iter(); recorre las páginas mediante cursores para que nunca tengas que gestionarlos manualmente.

3. Crea una ubicación en una sola llamada

locations.add() recibe cada campo obligatorio como argumento por nombre y los valida en el cliente (longitud del nombre, descripción de al menos 200 caracteres, categoría, país, ciudad) antes de realizar cualquier llamada de red, de modo que los datos no válidos provocan un fallo inmediato con un ValidationError claro.

Python
import listingsapi client = listingsapi.ListingsAPI() result = client.locations.add(  name="Acme Dental Uptown",  description=(      "Acme Dental Uptown is a family-owned dental practice on the Upper "      "West Side of New York offering preventive care, cosmetic dentistry, "      "orthodontics, and emergency appointments. Our board-certified team "      "combines modern equipment with a gentle, patient-first approach."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="482 Columbus Ave",  state_iso="NY",  postal_code="10024",  phone="6443859313",) print(result.location.id)print(result.location.name)

Las plataformas de publicación usan la descripción como texto principal de la ficha, por lo que la API exige al menos 200 caracteres. Obtén valores válidos de sub_category_id en client.subcategories().

El nuevo ID se devuelve como una cadena en base64, como TG9jYXRpb246MTY4MDg=. Los ID numéricos y en base64 son intercambiables en todos los casos en los que el SDK acepta un ID de ubicación, por lo que client.locations.retrieve(16808) y client.locations.retrieve("TG9jYXRpb246MTY4MDg=") obtienen la misma ubicación.

4. Responde a una reseña

Enumera las reseñas de una ubicación y luego responde usando el interactionId de la reseña:

Python
import listingsapi client = listingsapi.ListingsAPI() reviews = client.reviews.list(16808, first=10, rating_filters=[4, 5])for review in reviews:  print(review.rating, "-", review.get("content")) # A page can come back empty, and not every review is repliable: some sites# allow one owner reply per review, and some are read-only for the account.repliable = [r for r in reviews if r.get("canRespond")]if not repliable:  print("nothing to reply to")else:  client.reviews.respond(      interaction_id=repliable[0].interactionId,      content="Thank you for the kind review! We look forward to seeing you again soon.",  )

Comprueba canRespond antes de responder y nunca accedas a un elemento de una página por su índice sin comprobar primero que no esté vacía: reviews[0] en una página vacía genera IndexError, y responder a una reseña que la plataforma de origen ha cerrado provoca un fallo en la plataforma de publicación en lugar de en la API.

Si la plataforma rechaza la respuesta, el SDK genera ValidationError incluso cuando el estado HTTP es 200; nunca tienes que comprobar los indicadores success por tu cuenta.

5. Gestiona los errores

Python
import listingsapi try:  client = listingsapi.ListingsAPI(api_key="bad-key")  client.locations.list()except listingsapi.AuthenticationError as e:  print("Invalid key:", e.code)

Las claves no válidas dan lugar a una respuesta HTTP 401 con el código de plataforma SY90005; el SDK genera AuthenticationError. Como medida preventiva, también gestiona el mismo código de error si llega dentro de un cuerpo 200. Consulta Gestión de errores para ver la jerarquía completa de excepciones y la referencia de códigos de error para ver la matriz de estados HTTP.

Siguientes pasos