Documentación

Todo es una solicitud GET a https://api.mygeocode.com/v1/ con parámetros de consulta, respondida con JSON. Esta página cubre lo que comparten todos los endpoints. Las páginas de cada endpoint cubren sus parámetros y campos.

Tu primera solicitud

No se necesita clave para las primeras 2.500 solicitudes al día desde una dirección. Desde cualquier máquina:

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

Esa solicitud contó como 1 de las 2.500 solicitudes gratuitas que tu dirección tiene hoy. Con una clave se descontaría de la clave, y las cabeceras añadirían tus cifras de crédito y de espacios de IP. Las cabeceras de la respuesta te indican cómo vas:

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-free-remaining: 2499
x-quota-reset: 1756339200
x-request-id: 2726386e38428697

¿Vienes de otro proveedor?

Puede que no necesites el resto de esta página. Si tu código ya se comunica con Google Maps, Bing Maps, HERE, Mapbox, Geocode.Farm, Nominatim, OpenCage, LocationIQ, Geoapify, TomTom, MapQuest, Geocodio, PositionStack, ip-api, ipinfo, ipstack u Open-Elevation, tenemos un host que habla el formato de solicitud y respuesta de ese proveedor con nuestros datos detrás. Cambia el nombre de host, pon tu clave donde iba la anterior y conserva tu código de análisis. Lo mismo vale para la Google Maps JavaScript API, Bing Maps V8, HERE Maps for JavaScript, MapQuest.js y los plugins de geocodificación de MapLibre, Mapbox GL y Leaflet.

• Google Maps
• Bing Maps
• HERE
• Mapbox
• Geocode.Farm
• Nominatim
• OpenCage
• LocationIQ
• Geoapify
• TomTom
• MapQuest
• Geocodio
• PositionStack
• ip-api
• ipinfo
• ipstack
• Open-Elevation
• Bibliotecas de mapas en JavaScript

Cómo funcionan los hosts compatibles (drop-in): la matriz completa de hosts, la correspondencia de claves, la correspondencia de errores y una lista de comprobación para la migración.

URL base y endpoints

Solo se sirve HTTPS. Las solicitudes HTTP sin cifrar se rechazan con 400 en lugar de redirigirse, para que una clave nunca se envíe sin cifrar por accidente. Se admiten HTTP/2 y HTTP/3. Las respuestas se comprimen cuando el cliente acepta gzip o br.

El sobre de la respuesta

Cada respuesta es un objeto JSON con un status de ok o error.

• Con ok, sigue el contenido: results (un array) para los endpoints que pueden devolver varias coincidencias, result (un objeto o null) para la geocodificación inversa, y campos planos para las consultas de IP y de zona horaria.
• Con error, hay un objeto error con una cadena code, una frase message y, cuando corresponde, el param que lo causó. El estado HTTP coincide. Consulta errores.

Una consulta válida que no coincide con nada es ok con un array results vacío o un result null. Eso no es un error, y cuenta como solicitud.

Parámetros que aceptan todos los endpoints

Los nombres de los parámetros distinguen mayúsculas y minúsculas y van en minúsculas. Los parámetros desconocidos se ignoran, y los parámetros vacíos se tratan como ausentes, así que un formulario HTML puede enviar campos opcionales en blanco. Las coordenadas son grados decimales; lat de -90 a 90 y lon de -180 a 180. El texto es UTF-8 y debe ir codificado para URL.

La autenticación en un párrafo

La clave es opcional: cada dirección tiene 2.500 solicitudes gratuitas al día sin ella. La clave se envía como cabecera X-API-Key, como token Authorization: Bearer o como parámetro key; las claves son gratuitas, y una cuenta solo pide tu nombre, una dirección de correo electrónico y una contraseña. Cada clave tiene 2.500 solicitudes gratuitas al día propias; a partir de ahí, las solicitudes usan el crédito prepago de la cuenta a 0,0001 € cada una, o son gratuitas en una clave que pertenece a un paquete Unlimited (50 € al mes). Las solicitudes sin clave y las solicitudes con una clave desde la misma red comparten una sola cuota diaria. Una clave de pago por uso funciona desde dos direcciones IP por cada 24 horas móviles, una clave Unlimited desde tres. Las reglas completas están en la página de autenticación.

Cabeceras de cuota

Llamadas desde navegadores

CORS está habilitado en todos los endpoints y las cabeceras de cuota están expuestas, pero una clave en el código fuente de una página es pública y agotaría sus espacios de IP tras un par de visitantes. Haz las llamadas desde tu servidor; consulta claves y navegadores.

Control de versiones

El prefijo de ruta /v1/ es la versión. Dentro de una versión añadimos campos y parámetros, pero nunca los eliminamos ni les cambiamos el nombre, y nunca cambiamos el significado de un campo existente. Si alguna vez necesitamos romper algo, irá en /v2/ y /v1/ seguirá funcionando al menos seis meses después del anuncio. Las novedades se anuncian en la sección Noticias del blog.

Tu analizador JSON debe ignorar los campos que no conoce. Ese es el único requisito de compatibilidad futura.