Referencia rápida de la API de Places (nueva)

La API de Places (nueva) es un servicio web que devuelve datos de ubicación en formato JSON sobre establecimientos, ubicaciones geográficas y lugares de interés. Admite Text Search (nuevo), Nearby Search (nuevo), Autocomplete (nuevo), Place Details (nuevo) y Place Photos (nuevo).

API de Places (nueva): Datos clave

  • Producto: API de Places (nueva)
  • También conocida como: API de Places
  • Categoría: Lugares
  • Plataforma: Servicio web (REST)
  • Se ejecuta en: Servidor (código de backend)
  • Etapa de lanzamiento: GA
  • Ciclo de vida: Activo
  • Descripción general: Descripción general de la API de Places (nueva)
  • Disponibilidad regional: Global. Los proyectos con direcciones de facturación del EEE usan las Condiciones del Servicio de Google Maps Platform para el EEE (vigentes a partir del 8 de julio de 2025), en las que el contenido de la API de Places que no sea la latitud, la longitud y los IDs de lugar no se puede usar con ningún mapa, excepto a través del kit de IU de Places. Los resúmenes de lugares, opiniones y áreas potenciados por IA solo están disponibles en los idiomas y las regiones admitidos.

API de Places (nueva): Cuándo usarla

Usa la API de Places (nueva) en los siguientes casos:

  • Necesitas buscar lugares desde un servidor con una búsqueda de texto (Text Search (nuevo)) o alrededor de una ubicación (Nearby Search (nuevo)).
  • Necesitas predicciones de lugares o búsquedas de escritura anticipada de un backend a través de Autocomplete (nuevo).
  • Tienes un ID de lugar y necesitas detalles, como la dirección, el número de teléfono, la calificación, las opiniones o las fotos.
  • Necesitas resúmenes de lugares, opiniones o áreas potenciados por IA para un lugar.

No uses la API de Places (nueva) en los siguientes casos:

API de Places (nueva): Configuración

Paquetes oficiales de la API de Places (nueva):

  • npm: @googlemaps/places
  • pypi: google-maps-places
  • go: cloud.google.com/go/maps

API de Places (nueva): Errores comunes

  • Problema: Place Details (nuevo), Nearby Search (nuevo) y Text Search (nuevo) no tienen una lista predeterminada de campos devueltos; las solicitudes sin una máscara de campo devuelven un error. Solución: Pasa una máscara de campo de respuesta con el parámetro fields o $fields, o el encabezado X-Goog-FieldMask. Consulta /maps/documentation/places/web-service/choose-fields.
  • Problema: Si se omite o se reutiliza el token de sesión de Autocomplete (nuevo) después de que concluye una sesión, cada solicitud se factura por separado como SKU: Autocomplete Requests. Solución: Genera un token de sesión nuevo (se recomienda UUID v4) para cada sesión y finalízala con una solicitud de Place Details (nuevo) o Address Validation. Consulta /maps/documentation/places/web-service/place-session-tokens.
  • Problema: El código existente o generado por IA que llama a la API de Places (heredada) o a la API de Maps JavaScript PlacesService en un proyecto sin la API heredada habilitada falla con LegacyApiNotActivatedMapError. Solución: Migra las llamadas a la API de Places (nueva) y, luego, incluye la máscara de campo obligatoria. Consulta /maps/legacy#LegacyApiNotActivatedMapError.
  • Problema: Los IDs de lugar almacenados pueden quedar obsoletos. En ese caso, Place Details (nuevo) devuelve NOT_FOUND (HTTP 404), y los IDs con formato incorrecto o truncados devuelven HTTP 400 INVALID_ARGUMENT. Solución: Actualiza los IDs de lugar almacenados que tengan más de 12 meses de antigüedad con una solicitud de Place Details (nueva) que solo pida el campo id (sin cargo). Consulta /maps/documentation/places/web-service/place-id#refresh-id.

Qué puedes hacer con la API de Places (nueva)

Consulta las guías vinculadas a continuación para cada tarea o compara los productos en el Explorador de capacidades.

API de Places (nueva): IA generativa

API de Places (nueva): Places