Inicio rápido

Crea una cuenta. Es gratis, con 1000 créditos al mes y sin tarjeta. Luego crea una clave en Claves de API, dentro de la consola. Empieza con gm_ y solo la ves una vez: no guardamos la clave en sí, así que, si la pierdes, crea otra.

Mantén la clave fuera del código. Los ejemplos de aquí la leen de una variable de entorno:

export GMAPS_API_KEY=gm_…

Di qué buscas y dónde. Esta búsqueda pide panaderías en Curitiba:

curl -X POST https://api.gmaps.dev/v1/places/search \
  -H "Authorization: Bearer $GMAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["panadería"],
    "geo": { "location": "Curitiba, PR" }
  }'

La respuesta llega en data. Aquí está recortada a un lugar y unos pocos campos:

{
  "data": {
    "places": [
      {
        "id": "5b0c8e0a-2f4d-4c1e-9a57-3d2b8f6e1c90",
        "identity": {
          "cid": "12345678901234567890",
          "name": "Padaria Estrela do Centro",
          "category": "Padaria",
          "mapsUrl": "https://maps.google.com/?cid=12345678901234567890"
        },
        "contact": { "phones": ["+55 41 0000-0000"], "website": null },
        "location": {
          "city": "Curitiba",
          "state": "PR",
          "lat": -25.4296,
          "lng": -49.2713
        },
        "ratings": { "rating": 4.6, "reviewCount": 212 },
        "meta": { "cached": true }
      }
    ],
    "coverage": "partial",
    "placesKnown": 14,
    "collection": {
      "id": "8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31",
      "status": "queued"
    },
    "collectionError": null
  }
}

• places: hasta limit lugares. Son 20 si no pides otro número, y 120 como máximo. Lugares explica cada campo.
• coverage: cuánto de la zona habíamos buscado hace poco. fresh es toda la zona, partial es una parte y new es nada. Cobertura explica cómo llevamos esa cuenta.
• placesKnown: cuántos lugares ya teníamos guardados ahí. Todos son gratis.
• meta.cached, en cada lugar: true cuando ya lo teníamos guardado, así que no costó nada.
• collection: cuando lo que teníamos guardado no alcanza para limit y falta buscar parte de la zona, es la recopilación que busca el resto. Si no, vale null.
• collectionError: por qué no pudimos iniciar una recopilación, por ejemplo porque hoy ya no te quedan créditos. Igual recibes los lugares que teníamos.

Buscar es gratis. Pagas 1 crédito por cada lugar nuevo que encuentra una recopilación, y una búsqueda nunca cuesta más de limit créditos:

• 0Un lugar que ya guardamos llega en la misma respuesta, marcado con cached: true.
• 1Un lugar nuevo que encuentra una recopilación para ti.
• 1Correos electrónicos de un lugar nuevo, en los planes de pago: 1 crédito por lugar, solo cuando encontramos al menos uno.
• 0Búsquedas, estimaciones, exportaciones y consultar tu uso.
• 0Una recopilación que no encuentra nada.

Para ver cuántos créditos te quedan, llama a GET /v1/usage. Eso también es gratis. Los números de cada plan están en Límites.

Una recopilación tarda unos minutos. Mientras corre, puedes:

• repetir la misma búsqueda más tarde. Los lugares nuevos llegan junto con los demás, y esta vez son gratis.
• agregar "wait": 60, y la respuesta espera hasta 60 segundos a que lleguen lugares nuevos.
• leer la recopilación en GET /v1/collections/{id}, con el id que vino en la respuesta. Recopilaciones explica lo que contiene.

• Búsqueda: todos los campos de una búsqueda, las cuatro formas de indicar dónde y qué significa cada respuesta.
• Recopilaciones: busca en una ciudad entera, no solo en una página de resultados.
• Progreso en vivo: mira cómo llegan los lugares nuevos, uno por uno.
• Exportaciones: descarga una recopilación como archivo CSV, JSON o Excel.
• SDK de TypeScript: un método tipado para cada llamada.
• MCP para agentes: deja que un agente de IA busque lugares con tu clave.
• Errores: cada código de error y qué hacer con cada uno.