Atención: Pronto se implementarán cambios importantes en la API, por lo que será necesario llevar a cabo una migración. Consulta la página de próximas versiones y programación de la desactivación con frecuencia para enterarte de las novedades. También puedes registrarte en nuestra lista de distribución para recibir las novedades.

Utilizar datos de ubicación

En este tutorial se explica cómo crear y editar datos de ubicación. La API de Google 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 el recurso accounts.locations de la versión 4 de la API de Google My Business.

Antes de empezar

Para usar la API de Google My Business, debes registrar tu aplicación y obtener credenciales de OAuth 2.0. Para ver información detallada sobre cómo empezar a usar la API de Google My Business, consulta la sección Configuración básica.

Obtener una lista con una o varias ubicaciones

Si tu cuenta está asociada a una empresa con una o varias ubicaciones, te recomendamos que verifiques todas las ubicaciones. Utiliza la API accounts.locations.batchGet para obtener una lista con todas las ubicaciones asociadas a un usuario concreto.

Para obtener una lista con todas las ubicaciones de un usuario autenticado concreto, utiliza el código siguiente:

HTTP
POST
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations:batchGet

{
  "locationNames": [
    "accounts/{accountId}/locations/{locationId}",
    "accounts/{accountId}/locations/{locationId}"
  ],
}
Java

Esta función toma una clase ArrayList {String} de los nombres de las ubicaciones y devuelve una instancia de GetLocationsResponse, donde puedes obtener la lista de ubicaciones de la cuenta.

/*
 * Returns the specified locations for a given account.
 * @param accountName Name (resource path) of the account to get locations from.
 * @param nameList List of location names to return.
 * @return GetLocationsRequest Data model class containing results.
 * @throws IOException.
 */
private static List<Location> batchGetLocations(String accountName, ArrayList<String> nameList) throws IOException {
  GetLocationsRequest getLocationsRequest = new GetLocationsRequest();
  getLocationsRequest.setLocationNames(nameList);

  Mybusiness.Accounts.Locations.BatchGet locations =
      mybusiness.accounts().locations().batchGet(accountName, getLocationsRequest);

  GetLocationsResponse response = locations.execute();

  return response.getLocations();
}

Datos adicionales

La API de Java te da acceso a datos adicionales de campos para las instancias de ubicación. Usa los métodos siguientes para obtener datos adicionales sobre la cuenta:

  • getAdditionalCategories()
  • getAddress()
  • getBusinessHours()
  • getLabels()
  • getLocationKey()
  • getLocationName()
  • getName()
  • getPrimaryCategory()
  • getPrimaryPhone()
  • getServiceArea()
  • getStoreCode()
  • getWebsiteUrl()

Crear ubicaciones

Puedes crear ubicaciones para empresas usando el método accounts.locations.create con la API.

.

Para crear una ubicación, utiliza el código siguiente:

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

{
    "storeCode": "GOOG-SYD",
    "languageCode": "en-AU",
    "locationName": "Google Sydney",
    "primaryPhone": "02 9374 4000",
    "address": {
      "addressLines": [
        "Level 5",
        "48 Pirrama Road"
      ],
      "locality": "Pyrmont",
      "postalCode": "2009",
      "administrativeArea": "NSW",
      "regionCode": "AU"
    },
    "websiteUrl": "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"
        }
      ]
    },
    "primaryCategory": {
      "categoryId": "gcid:software_company"
    }
}
Java

Mediante esta función se crea una ubicación de ejemplo para Google Sydney.

/**
 * Creates a new location.
 * @param accountName The name (resource path) of the account to create a
 *   location for.
 * @return Location The data for the new location.
 * @throws Exception
 */

public static Location createLocation(String accountName) throws Exception {
    System.out.println("Creating Location");

    // Street address
    List<String> addressLines = new ArrayList();
    addressLines.add("Level 5, 48 Pirrama Road");
    Address address = new Address()
        .setAddressLines(addressLines)
        .setLocality("Pyrmont")
        .setAdministrativeArea("NSW")
        .setCountry("AU")
        .setPostalCode("2009");

    // Business hours
    List<TimePeriod> periods = new ArrayList<>();
    List<String> days = Arrays.asList("Monday", "Tuesday", "Wednesday", "Thursday", "Friday");

    for (String day : days) {
      TimePeriod period = new TimePeriod()
          .setOpenDay(day)
          .setOpenTime("9:00")
          .setCloseTime("17:00")
          .setCloseDay(day);
      periods.add(period);
    }
    BusinessHours businessHours = new BusinessHours()
        .setPeriods(periods);
    Location location = new Location()
        .setAddress(address)
        .setRegularHours(businessHours)
        .setLocationName("Google Sydney")
        .setStoreCode("GOOG-SYD")
        .setPrimaryPhone("02 9374 4000")
        .setPrimaryCategory(new Category().setName("Software Company"))
        .setWebsiteUrl("https://www.google.com.au/");

    Mybusiness.Accounts.Locations.Create createLocation =
        mybusiness.accounts().locations().create(accountName, location);
    createLocation.setRequestId("1a84939c-ab7d-4581-8930-ee35af6fefac");
    createLocation.setLanguageCode("en-AU");

    Location createdLocation = createLocation.execute();

    System.out.printf("Created Location:\n%s", createdLocation);
    return createdLocation;
  }

Eliminar ubicaciones

Puedes eliminar una ubicación usando el método accounts.locations.delete con la API.

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

HTTP
DELETE
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
{
  "account": {
    "accountName": "Anne Droyd"
  },
  "languageCode": "en",
  "validateOnly": "true"
}

Java
/**
 * Deletes the specified location.
 * @param locationName The name (resource path) of the location to delete.
 * @throws Exception
 */
public static void deleteLocation(String locationName) throws Exception {
  Location location = new Location();
  location.setName(locationName);
  Mybusiness.Accounts.Locations.Delete deleteLocation =
    mybusiness.accounts().locations().delete(locationName);
  deleteLocation.execute();
}

Consultar ubicaciones por nombre

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

Para consultar una ubicación por el nombre de la empresa, utiliza el código siguiente:

HTTP
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
Java

Esta función toma una lista con ubicaciones y devuelve los datos de la cuenta especificada, si existe.

/*
 * Returns the specified location
 * @param locationName The name (resource path) of the location to retrieve.
 * @return Location The requested location.
 */
private static Location getLocationByName(String locationName) throws IOException {
    Mybusiness.Accounts.Locations.Get location =
        mybusiness.accounts().locations().get(locationName);

    Location response = location.execute();
    return response;
}

Datos adicionales

La API de Java te da acceso a datos adicionales de campos para las instancias de ubicación. Usa los métodos siguientes para obtener datos adicionales sobre la cuenta:

  • getAdditionalCategories()
  • getAddress()
  • getBusinessHours()
  • getLabels()
  • getLocationKey()
  • getLocationName()
  • getName()
  • getPrimaryCategory()
  • getPrimaryPhone()
  • getServiceArea()
  • getStoreCode()
  • getWebsiteUrl()

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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}:googleUpdated

Si no hay resultados, se devuelve un código de estado HTTP 404 NOT FOUND.

Obtener una lista con todas las ubicaciones

Si tienes varias empresas asociadas a tu cuenta, te recomendamos que verifiques todas las ubicaciones. Puedes obtener una lista con todas las ubicaciones usando el método accounts.locations.list con la API.

Para que se devuelvan todas las ubicaciones, utiliza el código siguiente:

HTTP
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations
Java

Esta función devuelve la lista de ubicaciones de la cuenta especificada.

/*
 * Returns all locations for the specified account.
 * @param accountName The account for which to return locations.
 * @return List<Location> A list of all locations for the specified account.
 */
public static List<Location> listLocations(String accountName) throws Exception {
  Mybusiness.Accounts.Locations.List locationsList =
      mybusiness.accounts().locations().list(accountName);
  ListLocationsResponse response = locationsList.execute();
  List<Location> locations = response.getLocations();

  if (locations != null) {
    for (Location location : locations) {
      System.out.println(location.toPrettyString());
    }
  } else {
    System.out.printf("Account '%s' has no locations.", accountName);
  }
  return locations;
}

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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?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 situada más abajo).

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

A menos que se indique lo contrario, ninguna de las comparaciones de tokens distingue 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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}

Para filtrar ubicaciones en un radio de 1000 km de Boulder (Colorado, Estados Unidos), se utilizaría la solicitud siguiente:

GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?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
locationName

Es el nombre de la empresa.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationName:"Bajis" (concuerda con cualquier nombre de ubicación que contenga la cadena secundaria "Bajis")

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationName="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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=categories="french_restaurant"

primaryPhone

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

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=primaryPhone="+441234567890"

address.regionCode

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

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.regionCode="US"

address.administrativeArea

Es la subdivisión administrativa de mayor nivel que se utiliza en las direcciones postales de un país o una región.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.administrativeArea="CA"

address.locality

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

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.locality="New York"

address.postalCode

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

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.postalCode="12345"

locationKey.placeId

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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationKey.placeId="12345"

openInfo.status

Indica si la ubicación está abierta en ese momento (OPEN o CLOSED_PERMANENTLY).

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=openInfo.status="OPEN"

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=labels="newly open"

storeCode

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

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=storeCode="12345"

Predicados
locationState.isPublished

Indica si la ubicación está publicada en Google Maps (TRUE o FALSE).

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isPublished="TRUE"

locationState.isGoogleUpdated

Indica si el ID de sitio asociado a esa ubicación tiene actualizaciones (TRUE o FALSE).

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isGoogleUpdated="TRUE"

locationState.isSuspended

Indica si la ubicación está suspendida (TRUE o FALSE).

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isSuspended="TRUE"

locationState.isDuplicate

Indica si la ubicación es un duplicado de otra (TRUE o FALSE).

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isDuplicate="TRUE"

Funciones
distance

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

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?orderBy=locationName,storeCode

Aplicar un parche a una ubicación

Puedes actualizar uno o varios campos de una ubicación usando el método accounts.locations.patch con la API.

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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=FIELD_NAME
{
    "locationName": "Google Shoes",
    "primaryPhone": "(212) 553-5558",
}
Java

Esta función actualiza el campo locationName de una ubicación.

/**
 * Updates the specified fields in the specified location.
 * @param phone A string value for the location's primary phone.
 * @param name The name (resource path) for the location to update.
 * @throws Exception
 */
public static void updateLocation(String phone, String name) throws Exception {
    Location location = new Location()
        .setPrimaryPhone(phone);

    Mybusiness.Accounts.Locations.Patch updateLocation =
        mybusiness.accounts().locations().patch(name, location);
    updateLocation.setFieldMask("primary_phone");
    updateLocation.setLanguageCode("en-AU");
    Location updatedLocation = updateLocation.execute();

    System.out.printf("Updated Location:\n%s", updatedLocation);
  }