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:
- Crear ubicaciones
- Eliminar ubicaciones
- Consultar ubicaciones por su nombre de recurso
- Obtener una lista con todas las ubicaciones de una cuenta
- Actualizar uno o varios campos de una ubicación
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:
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:
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. :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Consultar la versión de Google Maps
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:
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):
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}
Filtrar los resultados de listas devueltas de ubicaciones
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:
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.
|
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.
|
phone_numbers.primary_phone |
Es el número de teléfono principal en formato E.164 (por ejemplo: "+441234567890").
|
storefront_address.region_code |
Es el código CLDR del país o la región de la dirección.
|
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.
|
storefront_address.locality |
Es la parte de la dirección que corresponde a la ciudad o la población.
|
storefront_address.postal_code |
Es el código postal de la dirección.
|
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.
|
openInfo.status |
Indica si la ubicación está abierta en ese momento (
|
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".
|
storeCode |
Es el identificador externo de esa ubicación, que debe ser único en una cuenta determinada.
|
| Funciones | |
distance |
Permite filtrar por la distancia a la que se encuentra la ubicación de un punto geográfico determinado.
|
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:
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:
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"
}