Usar datos de ubicación

En este tutorial se explica cómo crear y editar datos de ubicación. La API Business Information de My Business te permite hacer lo siguiente:

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

Antes de empezar

Para usar la API Business Information de My Business, debes registrar tu aplicación y obtener credenciales de OAuth 2.0. Consulta información detallada sobre cómo empezar a usar la API Business Information de My Business en la guía Configuración básica.

Crear una ubicación

Puedes crear una nueva ubicación para una empresa usando accounts.locations.create con la API Business Information de My Business.

Para crear una ubicación, usa el código 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"
      }
     }
}

Eliminar una ubicación

Puedes eliminar una ubicación usando locations.delete con la API Business Information de My Business.

Para eliminar una ubicación, usa el código siguiente:

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

Consultar ubicaciones por nombre

Si tienes varias empresas asociadas a tu cuenta, podría ser que quisieras consultar una sola ubicación. Puedes filtrar por el nombre de la empresa para obtener una ubicación específica usando el método locations.get.

Para consultar una ubicación por el nombre de la empresa, utiliza el código siguiente. Para obtener campos específicos, debes especificar un readMask. :

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

Consultar la versión de Google Maps

HTTP

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

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. Consulta más información sobre cómo gestionar las actualizaciones de Google en esta página.

Obtener una lista con todas las ubicaciones

Si gestionas una o varias ubicaciones, puedes obtener una lista con todas las ubicaciones de tu cuenta. Utiliza la API accounts.locations.list para obtener una lista con todas las ubicaciones asociadas a un usuario concreto.

Para obtener una lista con todas las ubicaciones que gestiona un usuario autenticado o que son de su propiedad, usa la siguiente consulta:

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

Usa un comodín '-' para la cuenta en la URL de solicitud. Así, incluirá las fichas que son indirectamente de su propiedad (esto es, que son suyas a través de un grupo, o bien que gestiona por ese medio):

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

Filtrar los resultados de listas devueltas de ubicaciones

HTTP

Puedes utilizar filtros para acotar los resultados que se devuelven cuando haces una llamada a accounts.locations.list. Para acotar una solicitud, añade 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 consulta

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

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

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

Combinar varios campos en una consulta de filtro

La API permite usar el operador AND para combinar todas las restricciones de campos. Sin embargo, al usar OR, todas las restricciones deben aplicarse al mismo campo. Por ejemplo, no se puede usar "locationName=A OR 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 las categorías "french_restaurant" o "european_restaurant" y la etiqueta "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 por cuenta

En el siguiente ejemplo se muestra cómo buscar ubicaciones a una distancia determinada de un punto geográfico concreto:

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

Para filtrar ubicaciones en un radio de 1000 millas de Boulder (Colorado, Estados Unidos), se utilizaría la solicitud 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 que se pueden usar

A continuación, se muestra la lista completa de todos los campos por los que se puede filtrar:

Campos Descripción y ejemplo
Campos de concordancia de cadena
title

Es el nombre de la empresa.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title:"Bajis" (concuerda con cualquier nombre de ubicación que contenga la cadena secundaria "Bajis")

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

categories

Es la combinación de la categoría principal y las adicionales. Ten en cuenta que debes omitir "gcid:". Si hay varias categorías, este filtro devuelve resultados si al menos una categoría concuerda 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 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 de mayor nivel que se utiliza en las direcciones postales de un país o una región.

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

storefront_address.locality

Es la parte de la dirección que corresponde a la ciudad o la población.

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 esa ubicación se ha verificado y está vinculada con Google Maps o aparece en dicha plataforma, este campo es igual al ID de sitio 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 en ese momento (OPEN o 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 un conjunto de cadenas de formato libre para que puedas etiquetar tu empresa. A diferencia de los demás campos, este valor debe concordar exactamente con una etiqueta completa, incluidas mayúsculas y minúsculas, y no solo con un token. Por ejemplo, si una etiqueta es "XX YY", no concordará 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 esa ubicación, que debe ser único en una cuenta determinada.

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

Funciones
distance

Permite filtrar por la distancia a la que se encuentra la ubicación de un punto geográfico determinado.

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 de forma ascendente o descendente por nombre de empresa o código de tienda. Si quieres aplicar varios criterios de ordenación, los debes separar con comas en la cadena orderBy, como en el ejemplo siguiente:

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

Aplicar un parche a una ubicación

Puedes actualizar uno o varios campos de una ubicación usando locations.patch con la API Business Information de My Business.

Para cambiar uno o varios campos de una ubicación, utiliza el código siguiente:

HTTP

Añade los campos y los valores actualizados con el campo de ubicación y utiliza una lista con campos actualizados separados por comas como valor de fieldMask.

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