Primeros pasos Geocoder API

La Geocoder API es un servicio que proporciona geocodificación convencional.

La geocodificación es el proceso que convierte direcciones (como "Prolongación Arenales 456, San Isidro, Lima") en coordenadas geográficas (como latitud -12.104418229714243 y longitud -77.03260748514282) que puedes usar para disponer marcadores en un mapa o posicionar el mapa.


Ejemplo de Solicitud y respuesta

Se puede acceder a través de HTTP, A continuación, se muestran ejemplos de las solicitudes y sus respuestas

Solicitud y respuesta de geocodificación (búsqueda de latitud y longitud)

En el siguiente ejemplo se solicita la latitud y longitud de “Joaquin Madrid N° 200” con ubigeo “150130”.
Para poder ubicar un listado de ubigeos se puede consultar Listado de Ubigeos

https://api.geodir.co/geocoder/geocoding/v1/geodir.address/simple?address=Joaquin Madrid N° 200&ubigeo=150130&token=YOUR_TOKEN

Se puede probar esto ingresando la URL en tu navegador web (reemplazando YOUR_TOKEN por tu clave real).

Se obtendrá una respuesta similar a esta:

Consulta la guía del desarrollador para obtener más información sobre la creación de url para la geocodificacion, los parámetros y la forma de la respuesta.
A continuación, se muestra un ejemplo de respuesta en formato JSON.

                                                                
    {
      "attribution": "http://geocoder.geodir.co/geocoder/home",
      "status": "OK",
      "version": "1.0",
      "address": [
        {
          "id": "geocoder.id_1",
          "status": "OK",
          "bbox": [
            -76.999574933,
            -12.1070467399999,
            -76.999574933,
            -12.1070467399999
          ],
          "type": "FeatureCollection",
          "geocoding": {
            "timestamp": 1510871998201,
            "query": {
              "text": "Av. Joaquin Madrid N° 200",
              "tokens": [
                "Av.","Joaquin","Madrid","N°","200"
              ],
              "size": 5,
              "lat": 0,
              "lon": 0
            }
          },
          "results": [
            {
              "id": 1,
              "id_str": "1",
              "geometry": {
                "type": "Point",
                "coordinates": [
                  -76.999574933,
                  -12.1070467399999
                ]
              },
              "center": [
                -76.999574933,
                -12.1070467399999
              ],
              "bbox": [
                -76.99967493300001,
                -12.1071467399999,
                -76.999474933,
                -12.1069467399999
              ],
              "type": "Feature",
              "nivelGeo": "NIVEL_PUERTA",
              "properties": {
                "region": "Peru",
                "label": "AV JOAQUIN MADRID N° 200",
                "direccion": "Av. Joaquin Madrid N° 200",
                "wayType": "AV",
                "way": "JOAQUIN MADRID",
                "block": 2,
                "number": 200,
                "nucleoType": null,
                "nucleo": null,
                "manzana": null
              }
            }
          ]
        }
      ],
      "comment": "El proceso demoro: 31 milliseconds  (0 seconds ) en procesar"
    }
                                                                
                                                            


Autenticación, cuotas

Para usar Geocoder API, primero debes registrarte.
Haz click en el botón y realiza el siguiente proceso:

Ir a Geocoder

1. Ir a Geocoder

2. Registrate

3. Verificar el token generado

Cuotas

Consulte la pagina para revisar los límites de uso (asociar a la página de geocoder con la lista de precios) para obtener información sobre las cuotas para Geocoder API.

Guía del desarrollador

¿Qué es la geocodificacion?

La geocodificación es el proceso que convierte direcciones (como "Prolongación Arenales 456, San Isidro, Lima") en coordenadas geográficas (como latitud -12.104418229714243 y longitud -77.03260748514282) que puedes usar para disponer marcadores en un mapa o posicionar el mapa.


Para Comenzar

En este documento se describe el servicio de Geocoder API el cual esta orientado a desarrolladores que deseen usar datos de geocodificacion.

La geocodificacion sin una herramienta toma tiempo, recursos y el no contar con ello le quita valiosa informacion a su sistema. Para evitar ello se recomienda realizar esta geocodificacion y guardar los resultados encontrados en tu propio diseño o para tus requerimientos.

Para usar Geocoder API, necesitas una clave API (revisando tu autenticacion y limites de uso de la API).

Formato de solicitud de Geocoder API
Una solicitud de Geocoder API debe respetar la siguiente forma:
https://api.geodir.co/geocoder/geocoding/v1/geodir.address/simple?parameters

Se recomienda usar HTTPS por temas de seguridad, siempre que esto sea posible.

Nota: tener cuidado con el tamaño de la cadena construida con los parámetros porque algunos navegadores pueden tener limites de caracteres diferentes.

Parametros (parameters)
Geocodificación (búsqueda de latitud/longitud)
  • address: la dirección que quieres geocodificar, en el formato utilizado por el servicio postal nacional. Se deben evitar elementos de dirección adicionales, como nombres de empresas y números de unidad, habitación o piso.
  • ubigeo: Valor del ubigeo de la direccion a buscar.
  • key Token: la clave de API del servicio es un token. Esta clave identifica tu aplicación a los fines de la administración de la cuota..
Respuestas de geocodificación

Las respuestas de geocodificacionse se devuelven en formato JSON.
En el ejemplo devuelve un respuesta json para la consulta “Joaquin Madrid N° 200" con ubigeo=”150130”

https://api.geodir.co/geocoder/geocoding/v1/geodir.address/simple?address=Joaquin Madrid N° 200&ubigeo=150130&token=YOUR_TOKEN

                                                        
    {
      "attribution": "http://geocoder.geodir.co/geocoder/home",
      "status": "OK",
      "version": "1.0",
      "address": [
        {
          "id": "geocoder.id_1",
          "status": "OK",
          "bbox": [
            -76.999574933,
            -12.1070467399999,
            -76.999574933,
            -12.1070467399999
          ],
          "type": "FeatureCollection",
          "geocoding": {
            "timestamp": 1510871998201,
            "query": {
              "text": "Av. Joaquin Madrid N° 200",
              "tokens": [
                "Av.","Joaquin","Madrid","N°","200"
              ],
              "size": 5,
              "lat": 0,
              "lon": 0
            }
          },
          "results": [
            {
              "id": 1,
              "id_str": "1",
              "geometry": {
                "type": "Point",
                "coordinates": [
                  -76.999574933,
                  -12.1070467399999
                ]
              },
              "center": [
                -76.999574933,
                -12.1070467399999
              ],
              "bbox": [
                -76.99967493300001,
                -12.1071467399999,
                -76.999474933,
                -12.1069467399999
              ],
              "type": "Feature",
              "nivelGeo": "NIVEL_PUERTA",
              "properties": {
                "region": "Peru",
                "label": "AV JOAQUIN MADRID N° 200",
                "direccion": "Av. Joaquin Madrid N° 200",
                "wayType": "AV",
                "way": "JOAQUIN MADRID",
                "block": 2,
                "number": 200,
                "nucleoType": null,
                "nucleo": null,
                "manzana": null
              }
            }
          ]
        }
      ],
      "comment": "El proceso demoro: 31 milliseconds  (0 seconds ) en procesar"
    }
                                                        
                                                    


Ten en cuenta que una respuesta JSON contiene dos elementos principales:

  • "status"contiene metadatos sobre la solicitud.
  • "results"contiene una matriz de información sobre direcciones geocodificadas e información sobre geometría.

Dentro de este atributo estara lo solitado longitud y latitud en ese orden el cual es el array coordinates que esta dentro del atributo geometry.
En algunos casos el geocodificador puede devolver varios resultados cuando las consultas de dirección sean ambiguas.
Ten en cuenta que estos resultados generalmente se deben analizar si quieres extraer valores de ellos. El análisis de JSON es relativamente fácil. Consulta Análisis de JSON para obtener información sobre algunos de los patrones de diseño recomendados.

Códigos de estado

El campo "status" en el objeto de la respuesta de geocodificación contiene el estado de la solicitud.
El campo "status" puede contener los siguientes valores:

  • "OK" indica que no ocurrieron errores, que la dirección se analizó correctamente y que se devolvió al menos un geocódigo.
  • ZERO_RESULTS indica que el geocódigo fue exitoso, pero no devolvió resultados. Esto puede ocurrir si se pasa un valor address inexistente al geocodificador.
  • "OVER_QUERY_LIMIT" indica que excediste tu cuota.
  • "INVALID_REQUEST" generalmente indica que falta la consulta (address, components o latlng).