Cómo trabajar con datos de ubicación

En este instructivo, se muestra cómo crear y editar datos de ubicación. La API de Business Information para Mi Negocio te permite hacer lo siguiente:

Las ubicaciones se pueden usar en Google Ads, pero deben estar verificadas para que puedan aparecer en la Búsqueda y Maps. Los datos de ubicación se representan con la colección accounts.locations.

Antes de comenzar

Antes de usar la API de Business Information para Mi Negocio, debes registrar tu aplicación y obtener credenciales de OAuth 2.0. Para obtener detalles sobre cómo comenzar a usar la API de My Business Business Information, consulta Configuración básica.

Cómo crear una ubicación

Puedes usar la API de Business Information para Mi Negocio para crear una ubicación nueva de una empresa con accounts.locations.create.

Para crear una ubicación, usa lo siguiente:

HTTP
POST
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False

{
    "storeCode": "GOOG-SYD",
    "languageCode": "en-AU",
    "title": "Google Sydney",
    "phoneNumbers": {
      "primaryPhone": "02 9374 4000"
     },
    "storefrontAddress": {
      "addressLines": [
        "Level 5",
        "48 Pirrama Road"
      ],
      "locality": "Pyrmont",
      "postalCode": "2009",
      "administrativeArea": "NSW",
      "regionCode": "AU"
    },
    "websiteUri": "https://www.google.com.au/",
    "regularHours": {
      "periods": [
        {
          "openDay": "MONDAY",
          "closeDay": "MONDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "TUESDAY",
          "closeDay": "TUESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "WEDNESDAY",
          "closeDay": "WEDNESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "THURSDAY",
          "closeDay": "THURSDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "FRIDAY",
          "closeDay": "FRIDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        }
      ]
    },
    "categories": {
      "primaryCategory": {
        "name": "gcid:software_company"
      }
     }
}

Cómo borrar una ubicación

Puedes usar la API de Business Information para Mi Negocio para borrar una ubicación con locations.delete.

Para borrar una ubicación, usa lo siguiente:

HTTP
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}

Obtén una ubicación por nombre

Si tienes muchas empresas asociadas con tu cuenta, es posible que quieras obtener una sola ubicación. Puedes filtrar por el nombre de la empresa para obtener una ubicación específica con locations.get.

Para obtener una ubicación por nombre, usa lo siguiente. Debes especificar una readMask para recuperar campos específicos. :

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

Devuelve la versión de Google Maps.

HTTP

Para que se devuelva la versión de Google Maps de una ubicación, agrega googleUpdated a la URL de la solicitud, como en el siguiente ejemplo:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}

Si no hay resultados, se devuelve un código de estado HTTP 404 NOT FOUND. Para obtener más detalles sobre cómo administrar las actualizaciones de Google, consulta Acepta o rechaza las actualizaciones.

Devuelve datos de ubicación extendidos y el estado de edición (v1alpha)

Para recuperar los datos de ubicación proporcionados por el comercio y los datos de ubicación para el consumidor junto con las etapas del ciclo de vida de edición por campo (como EDIT_LIFECYCLE_STAGE_PENDING o EDIT_LIFECYCLE_STAGE_REJECTED), la fuente de edición (SOURCE_API o SOURCE_UI) y los motivos de incumplimiento de política en una sola llamada, usa locations.getExtended en v1alpha:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}:getExtended

Para obtener ejemplos de respuestas completas y detalles sobre cómo interpretar el estado de edición por campo y los incumplimientos de política, consulta Verifica el estado de edición de las ubicaciones y los atributos.

Mostrar lista de ubicaciones

Cuando administras una o más ubicaciones, es posible que quieras enumerar todas las ubicaciones asociadas a tu cuenta. Usa la API de accounts.locations.list para enumerar todas las ubicaciones asociadas con un usuario.

Para enumerar todas las ubicaciones que pertenecen directamente a un usuario autenticado o que este administra, usa lo siguiente:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

Usa un comodín '-' para la cuenta en la URL de la solicitud para incluir las fichas de propiedad indirecta (propiedad o administración a través de un grupo):

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

Filtra los resultados cuando enumeres las ubicaciones

HTTP

Puedes usar filtros para limitar los resultados que se muestran cuando llamas a accounts.locations.list. Para filtrar una solicitud, agrega una expresión de filtro a la URL base, como se muestra en este ejemplo:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22

Sintaxis básica de las consultas

Una restricción tiene la siguiente sintaxis: <field><operator><value>, en la que el operador es EQUALS (=) o HAS (:). Los operadores EQUALS (=) y HAS (:) son equivalentes para todos los campos, excepto locationName (consulta la tabla a continuación).

Las comillas se codifican como "%22" y los espacios como signos más (+).

A menos que se indique lo contrario, todas las comparaciones son comparaciones de tokens que no distinguen mayúsculas de minúsculas. Por ejemplo, "4 drive" coincidiría con "4, Privet Drive".

Combina varios campos en una consulta de filtro

La API permite que AND conecte todas las restricciones de campos. Sin embargo, cuando se trata de la palabra clave OR, todas las restricciones deben aplicarse al mismo campo. Por ejemplo, no se permite locationName=A O labels=B.

Ejemplo

En el siguiente ejemplo, se muestra una expresión de filtro que devuelve todas las ubicaciones con el nombre "Pepé Le Pew". Muestra categorías para "french_restaurant" o "european_restaurant", y una etiqueta de "newly open".

locationName=%22Pepé+Le+Pew%22+AND+
(categories=%22french_restaurant%22+OR+
categories=%22european_restaurant%22)+AND+
labels=%22newly+open%22

Buscar por distancia o cuenta

En el siguiente ejemplo, se muestra cómo puedes buscar ubicaciones dentro de una distancia determinada desde un punto geográfico:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}

Para filtrar las ubicaciones que se encuentran a menos de 1,000 millas de Boulder, Colorado, EE.UU., haz lo siguiente:

GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0

Lista de todos los campos de filtro compatibles

La siguiente es una lista exhaustiva de todos los campos que se pueden usar para filtrar:

Campos Descripción y ejemplo
Campos de coincidencia de cadenas
title

El nombre de la empresa en el mundo real

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title:"Bajis" (coincide con cualquier nombre de ubicación que tenga "Bajis" como subcadena)

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title="Bajis" (coincide con cualquier nombre de ubicación que tenga "Bajis" como token o palabra)

categories

Es la combinación de la categoría principal y las categorías adicionales. Ten en cuenta que se debe omitir "gcid:". Si hay varias categorías, este filtro coincide si al menos una categoría coincide con este patrón.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=categories="french_restaurant"

phone_numbers.primary_phone

Es el número de teléfono principal en formato E.164 (por ejemplo: "+441234567890").

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=phone_numbers.primary_phone="+441234567890"

storefront_address.region_code

Es el código de región de CLDR del país o la región de la dirección.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.region_code="US"

storefront_address.administrative_area

Es la subdivisión administrativa más alta que se usa para las direcciones postales de un país o región.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.administrative_area="CA"

storefront_address.locality

La parte de la dirección que corresponde a la ciudad o localidad

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.locality="New York"

storefront_address.postal_code

Es el código postal de la dirección.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.postal_code="12345"

metadata.place_id

Si se verificó esta ubicación y está conectada a Google Maps o aparece en este servicio, este campo es igual al ID de lugar de la ubicación.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=metadata.place_id="12345"

openInfo.status

Indica si la ubicación está abierta para el negocio (OPEN, CLOSED_PERMANENTLY)

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="OPEN"

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="CLOSED_PERMANENTLY"

labels

Es una colección de cadenas de formato libre que te permiten etiquetar tu empresa. A diferencia de todos los demás campos, este valor debe coincidir exactamente con una etiqueta completa, incluidas las mayúsculas y minúsculas, y no solo con un token. Por ejemplo, si una etiqueta es "XX YY", no coincidirá con "XX" ni con "xx yy".

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=labels="newly open"

storeCode

Es el identificador externo de esta ubicación, que debe ser único dentro de una cuenta determinada.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storeCode="12345"

Funciones
distance

Te permite filtrar según la distancia de la ubicación desde un punto geográfico.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(1.0, -25.0))<1000.0

Ordenar por campo de consulta

Puedes ordenar los resultados por nombre de la empresa o código de tienda, en orden ascendente o descendente. Los criterios de ordenamiento múltiples se separan con comas en la cadena orderBy, como en el siguiente ejemplo:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode

Cómo aplicar un parche a una ubicación

Usa la API de Business Information para Mi Negocio para actualizar uno o más campos de una ubicación con locations.patch.

Para cambiar uno o más campos de una ubicación, usa lo siguiente:

HTTP

Agrega los campos y los valores actualizados con el campo de ubicación y usa una lista separada por comas de los campos actualizados como el valor de fieldMask.

PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
    "title": "Google Shoes"
}