Listings APIListings API
Iniciar sesión

Ubicaciones

Enumera, crea, actualiza, archiva, busca y consulta ubicaciones mediante client.locations.

Todos los métodos de ubicación están en client.locations. Instala el SDK y configura tu clave antes de usarlos; consulta Instalación e Inicio rápido.

IDs de ubicación

Los métodos que reciben un location_id aceptan tanto un ID numérico (16808) como su equivalente codificado en base64 ("TG9jYXRpb246MTY4MDg="). El SDK codifica los IDs numéricos automáticamente, por lo que ambas formas son intercambiables:

Python
# These are equivalentclient.locations.retrieve(16808)client.locations.retrieve("TG9jYXRpb246MTY4MDg=")

locations.add

Crea una ubicación en una sola llamada con cada campo obligatorio como argumento con nombre. Esta es la forma recomendada de crear ubicaciones. El SDK valida en el cliente los requisitos de creación de la API y lanza ValidationError antes de realizar cualquier llamada de red, por lo que una carga útil incorrecta provoca un error inmediato con un mensaje claro.

Python
client.locations.add(    *,    name: str,    description: str,    sub_category_id: int,    country_iso: str,    city: str | None = None,    street: str | None = None,    state_iso: str | None = None,    postal_code: str | None = None,    phone: str | None = None,    website: str | None = None,    store_id: str | None = None,    hide_address: bool | None = None,    business_hours: list[dict] | None = None,    service_area: dict | None = None,    place_action_links: list[dict] | None = None,    enabled_site_ids: list[int] | None = None,    additional_fields: dict | None = None,) -> APIObject
ArgumentoTipoDescripción
namestrNombre del negocio, de 2 a 150 caracteres. Obligatorio.
descriptionstrDescripción del negocio, mínimo 200 caracteres. Las plataformas de publicación la usan como texto principal de la ficha. Obligatoria.
sub_category_idintID de la subcategoría principal. Usa client.subcategories() para obtener IDs válidos. Obligatorio.
country_isostrCódigo ISO del país de dos letras. Usa client.countries() para obtener los países admitidos. Obligatorio.
citystrCiudad. Obligatoria para los países cuyo sistema de direcciones incluye la ciudad; omítela solo para negocios con área de servicio que tengan hide_address=True.
streetstrDirección postal.
state_isostrCódigo ISO del estado o la región.
postal_codestrCódigo postal o ZIP.
phonestrNúmero de teléfono principal, validado para el país.
websitestrURL del sitio web del negocio.
store_idstrTu código único de tienda; debe ser único en toda la cuenta.
hide_addressboolOcultar la dirección postal (negocios con área de servicio).
business_hourslist[dict]Horario semanal, e.g. [{"day": "MONDAY", "slots": [...]}].
service_areadictConfiguración del área de servicio: {businessType, regionCode, placeInfos}.
place_action_linkslist[dict]Enlaces de acción de Google, e.g. [{"placeActionType": "APPOINTMENT", "uri": "https://...", "isPreferred": True}].
enabled_site_idslist[int]IDs de los sitios en los que publicar esta ubicación, cuando quieras usar un subconjunto de los sitios de tu plan. Usa client.plan_sites() para obtener los IDs.
additional_fieldsdictCampos camelCase adicionales que se incorporan a la carga útil sin modificaciones.

La validación en el cliente comprueba que name tenga entre 2 y 150 caracteres, que description tenga al menos 200 caracteres, que sub_category_id y country_iso estén presentes y que city esté presente salvo que hide_address=True.

El valor devuelto es la carga útil de creación: .location contiene la nueva ubicación. Nunca necesitas comprobar indicadores de éxito; el SDK lanza ValidationError cuando la API rechaza la carga útil.

Python
result = client.locations.add(  name="Acme Dental",  description=(      "Acme Dental is a family-owned dental practice offering general, "      "cosmetic, and pediatric dentistry in the heart of New York. Our "      "team provides cleanings, fillings, crowns, whitening, and same-day "      "emergency care in a modern, comfortable office with weekend hours "      "and easy online booking for new and returning patients."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="123 Jump Street",  state_iso="NY",  postal_code="10013",  phone="6443859313",  website="https://acmedental.example.com",  store_id="NYC-001",  place_action_links=[      {"placeActionType": "APPOINTMENT", "uri": "https://acmedental.example.com/book", "isPreferred": True},  ],  enabled_site_ids=[1, 24, 87],)print("Created:", result.location.id, result.location.name)

locations.list

Lista las ubicaciones con paginación basada en cursores. Devuelve un SyncPage.

Python
client.locations.list(    *,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage
Python
# First page of 25page = client.locations.list(first=25)for loc in page:  print(loc.name, loc.city) # Next page manuallyif page.has_more:  page2 = page.next_page() # Auto-paginate all locationsfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

locations.retrieve

Obtén una única ubicación por ID. Lanza NotFoundError si el ID no existe.

Python
client.locations.retrieve(location_id: str | int) -> APIObject
Python
loc = client.locations.retrieve(16808)print(loc.name, loc.street, loc.city)

locations.list_by_ids

Obtén varias ubicaciones a partir de una lista de IDs (numéricos o en base64) en una sola llamada.

Python
client.locations.list_by_ids(location_ids: list[str | int]) -> list[APIObject]
Python
locs = client.locations.list_by_ids([16808, 16809, "TG9jYXRpb246MTQwMjQ="])for loc in locs:  print(loc.id, loc.name)

locations.list_by_store_codes

Obtén las ubicaciones que coincidan con los códigos de tienda indicados.

Python
client.locations.list_by_store_codes(store_codes: list[str]) -> list[APIObject]
Python
locs = client.locations.list_by_store_codes(["SF-001", "NYC-042"])for loc in locs:  print(loc.storeId, loc.name)

locations.search

Busca ubicaciones por palabra clave en el nombre, la dirección o el ID de tienda. Devuelve un SyncPage.

Python
client.locations.search(    query: str,    *,    fields: list[str] | None = None,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage
Python
# Search all fieldspage = client.locations.search("downtown dental", first=10) # Restrict to name onlypage = client.locations.search("Acme Dental", fields=["name"], first=10) for loc in page:  print(loc.name, loc.city)

locations.create

Crea una ubicación a partir de un dict de entrada sin procesar con nombres de campo camelCase. Usa preferentemente locations.add para trabajar con argumentos con nombre y validación en el cliente; usa create cuando ya tengas una carga útil camelCase.

Python
client.locations.create(input: dict) -> APIObject

Campos obligatorios para la API: name, description (mínimo 200 caracteres), subCategoryId, countryIso y city (para países cuyo sistema de direcciones incluye la ciudad).

Python
result = client.locations.create({  "name": "Acme Dental Brooklyn",  "description": (      "Acme Dental Brooklyn is a family-owned dental practice offering "      "general, cosmetic, and pediatric dentistry. Our team provides "      "cleanings, fillings, crowns, whitening, and same-day emergency "      "care in a modern, comfortable office with weekend hours and easy "      "online booking for new and returning patients across Brooklyn."  ),  "subCategoryId": 1432,  "countryIso": "US",  "city": "Brooklyn",  "street": "88 Court St",  "stateIso": "NY",  "postalCode": "11201",  "phone": "6443859314",  "storeId": "NYC-002",})print("Created:", result.location.id)

locations.update

Actualiza una ubicación. Pasa id junto con los campos que quieras modificar (camelCase). El id puede ser numérico o estar en base64; el SDK lo codifica automáticamente.

Python
client.locations.update(input: dict) -> APIObject
Python
result = client.locations.update({  "id": 16808,  "phone": "6443859399",  "street": "125 Jump Street",})print("Updated:", result.location.id)

locations.archive

Archiva una o más ubicaciones.

Python
client.locations.archive(location_ids: list[str | int]) -> APIObject
Python
result = client.locations.archive([16808, 16809])print(result.to_dict())

locations.cancel_archive

Cancela un archivado programado.

Python
client.locations.cancel_archive(    location_ids: list[str | int],    selection_type: str,    changed_by: str,) -> APIObject
Python
client.locations.cancel_archive(  [16808],  selection_type="manual",  changed_by="admin@example.com",)

Consulta también

  • Publicaciones: publica anuncios, eventos y ofertas
  • Fichas: consulta el estado de sincronización de cada ubicación
  • Reseñas: lista las reseñas y respóndelas
  • Analítica: analítica de perfiles de Google, Bing y Facebook