Primeros pasos Geocoder API

Geocoder API es un servicio que proporciona geocodificación directa, este servicio está disponible para cliente JavaScript.

La geocodificación es el proceso que convierte direcciones (como la dirección de una calle) en coordenadas geográficas (latitud y longitud) que puedes usar para disponer marcadores en un mapa o posicionar el mapa.


Ejemplo de Solicitud y respuesta

Puedes acceder a Geocoder API a través de una interfaz HTTP. A continuación, un ejemplo de solicitud de ingreso y salida.

Mediante JAVASCRIPT


Solicitud:

Para este ejemplo se solicita la dirección:
Jr. Paracas 523, distrito Pueblo Libre (ubigeo 150121)


    [
         {
            "id":   1,               // Id de la Dirección (opcional)
            "ubigeo": "150121",             // Ubigeo (Obligatorio)
            "address": "jr paracas 523"     // Dirección (Obligatorio)
         }
    ]         
                           
                        


Respuesta:

Los resultados están en formato GeoJSON

                                    
    {
        "attribution": "https://www.geodir.co/geocoder",
        "status": "OK",                 // contiene metadatos sobre la solicitud.
        "version": "1.0",               // versión de motor de georreferenciación
        "address": [                // contiene el conjunto de direcciones georreferenciadas
            {   
                "id": "geocoder.id_1",  // id de la dirección << geocoder.id_ + ‘sec’>>
                "status": "OK",         // contiene metadatos proceso de georreferenciación 
                "bbox": [               // Describe la extensión geográfica.
                    -77.07638036734684,
                    -12.071689693877474,
                    -77.07638036734684,
                    -12.071689693877474
                ],
                "type": "FeatureCollection",        
                "geocoding": {          // Datos generales de la geo codificación
                    "timestamp": 1503328200459, // Fecha
                    "query": {          // Descomposición de la dirección
                        "text": "jr paracas 523",   // Dirección ingresado por el cliente
                        "tokens": [         // Descomposición de básica de la dirección.
                            "jr",
                            "paracas",
                            "523"
                        ],
                        "size": 3,          // Cantidad de palabras
                        "lat": 0,               // Latitud (ubicación de consulta)
                        "lon": 0                // Longitud (ubicación de consulta)
                    }
                },
                "results": [                // Resultados de la georreferenciación en orden de relevancia
                    {
                        "id": 1,                // identificador de resultado (int)
                        "id_str": "1",          // identificador de resultado (String)
                        "geometry": {           // Geometría Formato (GEOJSON)
                            "type": "Point",        // Tipo de Geometría  (Point, LineString, Polygon, MultiPoint, 
                            "coordinates": [           MultiLineString, MultiPolygon, y GeometryCollection)
                                -77.07638036734684,
                                -12.071689693877474
                            ]
                        },
                        "center": [         // Centroide de la Geometría
                            -77.07638036734684,
                            -12.071689693877474
                        ],
                        "bbox": [           // Extensión geográfica
                            -77.07648036734685,
                            -12.071789693877474,
                            -77.07628036734684,
                            -12.071589693877474
                        ],
                        "type": "Feature",          
                        "nivelGeo": "NIVEL_PUERTA", // Nivel de georreferenciación
                        "properties": {         // Detalle del resultado de la georreferenciación.
                            "region": "Peru",       // Pais
                            "label": "PQ PARACAS N° 523",   // Dirección normalizada
                            "direccion": "jr paracas 523",  // Dirección ingresada por el usuario
                            "wayType": "PQ",        // Tipo de via
                            "way": "PARACAS",       // Nombre de la via
                            "block": 5,         // Cuadra
                            "number": 523,          // Numero de puerta
                            "nucleoType": null,     // Tipo de Núcleo Urbano
                            "nucleo": null,         // Nombre del núcleo urbano
                            "manzana": null     // Manzana
                        }
                    }
                ]
            },{
             .
             .
             .
            }
        ],
        "comment": "El proceso demoro: 50 milliseconds  (0 seconds ) en procesar"
    }
                                            
                                



Para procesar por lotes (varias direcciones)


Solicitud:

Para este ejemplo se solicita las direcciones:
- Jr. Paracas 523, distrito Pueblo Libre (ubigeo 150121)
- Av. Arequipa 2888, distrito San Isidro (ubigeo 150131)
- Av. Benavides 2830, distrito Santiago de Surco (ubigeo 150140)

                                    
    [
         {
            "id":   1,               // Id de la Dirección (opcional)
            "ubigeo": "150121",             // Ubigeo (Obligatorio)
            "address": "jr paracas 523"     // Dirección (Obligatorio)
         },
         {
            "id":   2,               // Id de la Dirección (opcional)
            "ubigeo": "150131",             // Ubigeo (Obligatorio)
            "address": "av arequipa 2888"       // Dirección (Obligatorio)
         },
         {
            "id":   3 ,              // Id de la Dirección (opcional)
            "ubigeo": "150140",             // Ubigeo (Obligatorio)
            "address": "av benavides 2830"      // Dirección (Obligatorio)
         }
    ]
                                
                                


Respuesta:

Los resultados están en formato GeoJSON

                                    
    {
        "attribution": "https://www.geodir.co/geocoder",
        "status": "OK",
        "version": "1.0",
        "address": [
            {
                "id": "geocoder.id_1",
                "status": "OK",
                "bbox": [
                    -77.07638036734684,
                    -12.071689693877474,
                    -77.07638036734684,
                    -12.071689693877474
                ],
                "type": "FeatureCollection",
                "geocoding": {
                    "timestamp": 1503420289984,
                    "query": {
                        "text": "jr paracas 523",
                        "tokens": [
                            "jr",
                            "paracas",
                            "523"
                        ],
                        "size": 3,
                        "lat": 0,
                        "lon": 0
                    }
                },
                "results": [
                    {
                        "id": 1,
                        "id_str": "1",
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -77.07638036734684,
                                -12.071689693877474
                            ]
                        },
                        "center": [
                            -77.07638036734684,
                            -12.071689693877474
                        ],
                        "bbox": [
                            -77.07648036734685,
                            -12.071789693877474,
                            -77.07628036734684,
                            -12.071589693877474
                        ],
                        "type": "Feature",
                        "nivelGeo": "NIVEL_PUERTA",
                        "properties": {
                            "region": "Peru",
                            "label": "PQ PARACAS N° 523",
                            "direccion": "jr paracas 523",
                            "wayType": "PQ",
                            "way": "PARACAS",
                            "block": 5,
                            "number": 523,
                            "nucleoType": null,
                            "nucleo": null,
                            "manzana": null
                        }
                    }
                ]
            },
            {
                "id": "geocoder.id_2",
                "status": "OK",
                "bbox": [
                    -77.03320206787755,
                    -12.093774229306034,
                    -77.03320206787755,
                    -12.093774229306034
                ],
                "type": "FeatureCollection",
                "geocoding": {
                    "timestamp": 1503420289984,
                    "query": {
                        "text": "av arequipa 2888",
                        "tokens": [
                            "av",
                            "arequipa",
                            "2888"
                        ],
                        "size": 3,
                        "lat": 0,
                        "lon": 0
                    }
                },
                "results": [
                    {
                        "id": 1,
                        "id_str": "1",
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -77.03320206787755,
                                -12.093774229306034
                            ]
                        },
                        "center": [
                            -77.03320206787755,
                            -12.093774229306034
                        ],
                        "bbox": [
                            -77.03330206787756,
                            -12.093874229306033,
                            -77.03310206787755,
                            -12.093674229306034
                        ],
                        "type": "Feature",
                        "nivelGeo": "NIVEL_PUERTA",
                        "properties": {
                            "region": "Peru",
                            "label": "AV AREQUIPA N° 2888",
                            "direccion": "av arequipa 2888",
                            "wayType": "AV",
                            "way": "AREQUIPA",
                            "block": 28,
                            "number": 2888,
                            "nucleoType": null,
                            "nucleo": null,
                            "manzana": null
                        }
                    }
                ]
            },
            {
                "id": "geocoder.id_3",
                "status": "OK",
                "bbox": [
                    -77.00483892058163,
                    -12.12840913899993,
                    -77.00483892058163,
                    -12.12840913899993
                ],
                "type": "FeatureCollection",
                "geocoding": {
                    "timestamp": 1503420289984,
                    "query": {
                        "text": "av benavides 2830",
                        "tokens": [
                            "av",
                            "benavides",
                            "2830"
                        ],
                        "size": 3,
                        "lat": 0,
                        "lon": 0
                    }
                },
                "results": [
                    {
                        "id": 1,
                        "id_str": "1",
                        "geometry": {
                            "type": "Point",
                            "coordinates": [
                                -77.00483892058163,
                                -12.12840913899993
                            ]
                        },
                        "center": [
                            -77.00483892058163,
                            -12.12840913899993
                        ],
                        "bbox": [
                            -77.00493892058164,
                            -12.128509138999929,
                            -77.00473892058163,
                            -12.12830913899993
                        ],
                        "type": "Feature",
                        "nivelGeo": "NIVEL_PUERTA_COLINDANTE",
                        "properties": {
                            "region": "Peru",
                            "label": "AV ALFREDO BENAVIDES N° 2830",
                            "direccion": "av benavides 2830",
                            "wayType": "AV",
                            "way": "ALFREDO BENAVIDES",
                            "block": 28,
                            "number": 2830,
                            "nucleoType": null,
                            "nucleo": null,
                            "manzana": null
                        }
                    }
                ]
            }
        ],
        "comment": "El proceso demoro: 65 milliseconds  (0 seconds ) en procesar"
    }
                                              
                                          



Mediante URL


La geocodificación mediante URL, permite hacer sencilla la forma de hacer consultas y obtener respuestas desde diferentes plataformas (desktop, web, móvil). Consta de 3 parámetros:

• Address: Dirección que se desea geocodificar.

• Ubigeo: Distrito, si no conoces el ubigeo del distrito que buscas, ingresa al portal Ubigeos del Perú aquí podrás encontrar el ubigeo de cualquier distrito del Perú.

• Token: Clave token que se generara automáticamente al registrarte en Geodir Geocoder, puedes registrarte haciendo clic en Registro Geodir.

Solicitud:

Para este ejemplo se solicita la dirección de la Municipalidad de San Borja:
- Joaquin Madrid N°200 (ubigeo 150130)

Para poder hacer una nueva consulta solo debemos actualizar los datos de los 3 parámetros ingresados (address, ubigeo, token).

curl "http://geocoder.geodir.co/geocoder.api/geocoding/1.0/geodir.address/simple?address=Joaquin Madrid N° 200&ubigeo=150130&token=9a606293-47c7-4d6b-946d-eb37b2dfe3cb"


Respuesta:

Los resultados están en formato GeoJSON

Entre los parámetros de respuesta mas importantes tenemos las coordenadas (coordinates) y el nivel de geocodificación (nivelGeo).

                                    
        {
          "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"
        }
                                            
                                


Guía del desarrollador

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.


En este documento se describe el servicio web Geocoder API. Está orientado a desarrolladores de sitios web que deseen usar datos de geocodificación dentro de mapas proporcionados por Geocoder API.

Nota: Este servicio generalmente está diseñado para geocodificar direcciones estáticas (ya conocidas) para la disposición de contenido de la aplicación en un mapa. No se concibió para responder en tiempo real a las entradas del usuario.

La geocodificación es una tarea que consume tiempo y recursos. Siempre que sea posible, realiza una geocodificación previa de las direcciones conocidas (usando la Geocoder API que se describe aquí u otro servicio de geocodificación) y guarda tus resultados en un caché temporal de tu propio diseño.


Para usar Geocoder API, necesitas una clave Token. Antes de comenzar a realizar desarrollos con Geocoder API, revisa los requisitos de autenticación y los límites de uso de la API.

Formato de solicitud de Geocoder API

Una solicitud de Geocoder API debe respetar la siguiente forma:


    [
         {
            "id":   1               // Id de la Dirección (opcional)
            "ubigeo": "150121",             // Ubigeo (Obligatorio)
            "address": "jr paracas 523"     // Dirección (Obligatorio)
         }
    ]         
                                             
                                          


Para acceder a la Geocoder API a través de HTTP, usa:

La seguridad es importante y se recomienda usar HTTPS, siempre que sea posible, especialmente para aplicaciones que incluyen en las solicitudes datos confidenciales de los usuarios, como la ubicación. El uso de encriptación HTTPS aporta más seguridad a tu aplicación y la hace más resistente contra las intromisiones o la manipulación.

Geocodificación (búsqueda de latitud/longitud)

Una solicitud de Geocoder API debe respetar la siguiente forma:

json (recomendado) indica el formato de salida en JavaScript Object Notation (JSON)

Parámetros obligatorios en una solicitud de geocodificación:

  • 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. Consulta las preguntas frecuentes para obtener más información.
  • 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. Infórmate acerca de cómo obtener un Key Token.
Respuestas de geocodificación

Las respuestas de geocodificación se devuelven en el formato indicado por el marcador output en la ruta de acceso de la dirección URL de la solicitud.

En este ejemplo, Geocoder API solicita una respuesta json para una consulta sobre " jr paracas 523, Pueblo Libre, Lima".

Esta solicitud muestra el uso del marcador output de JSON:

Respuesta: Los resultados están en formato GeoJSON.

                                                      
    {
        "attribution": "https://www.geodir.co/geocoder",
        "status": "OK",                 // contiene metadatos sobre la solicitud.
        "version": "1.0",               // versión de motor de georreferenciación
        "address": [                // contiene el conjunto de direcciones georreferenciadas
            {   
                "id": "geocoder.id_1",  // id de la dirección << geocoder.id_ + ‘sec’>>
                "status": "OK",         // contiene metadatos proceso de georreferenciación 
                "bbox": [               // Describe la extensión geográfica.
                    -77.07638036734684,
                    -12.071689693877474,
                    -77.07638036734684,
                    -12.071689693877474
                ],
                "type": "FeatureCollection",        
                "geocoding": {          // Datos generales de la geo codificación
                    "timestamp": 1503328200459, // Fecha
                    "query": {          // Descomposición de la dirección
                        "text": "jr paracas 523",   // Dirección ingresado por el cliente
                        "tokens": [         // Descomposición de básica de la dirección.
                            "jr",
                            "paracas",
                            "523"
                        ],
                        "size": 3,          // Cantidad de palabras
                        "lat": 0,               // Latitud (ubicación de consulta)
                        "lon": 0                // Longitud (ubicación de consulta)
                    }
                },
                "results": [                // Resultados de la georreferenciación en orden de relevancia
                    {
                        "id": 1,                // identificador de resultado (int)
                        "id_str": "1",          // identificador de resultado (String)
                        "geometry": {           // Geometría Formato (GEOJSON)
                            "type": "Point",        // Tipo de Geometría  (Point, LineString, Polygon, MultiPoint, 
                            "coordinates": [           MultiLineString, MultiPolygon, y GeometryCollection)
                                -77.07638036734684,
                                -12.071689693877474
                            ]
                        },
                        "center": [         // Centroide de la Geometría
                            -77.07638036734684,
                            -12.071689693877474
                        ],
                        "bbox": [           // Extensión geográfica
                            -77.07648036734685,
                            -12.071789693877474,
                            -77.07628036734684,
                            -12.071589693877474
                        ],
                        "type": "Feature",          
                        "nivelGeo": "NIVEL_PUERTA", // Nivel de georreferenciación
                        "properties": {         // Detalle del resultado de la georreferenciación.
                            "region": "Peru",       // Pais
                            "label": "PQ PARACAS N° 523",   // Dirección normalizada
                            "direccion": "jr paracas 523",  // Dirección ingresada por el usuario
                            "wayType": "PQ",        // Tipo de via
                            "way": "PARACAS",       // Nombre de la via
                            "block": 5,         // Cuadra
                            "number": 523,          // Numero de puerta
                            "nucleoType": null,     // Tipo de Núcleo Urbano
                            "nucleo": null,         // Nombre del núcleo urbano
                            "manzana": null     // Manzana
                        }
                    }
                ]
            },{
             .
             .
             .
            }
        ],
        "comment": "El proceso demoro: 50 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.

Generalmente, para las búsquedas de direcciones solo se devuelve una entrada en la matriz "results", aunque 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 y podría contener información de depuración para ayudarte a localizar por qué falló la geocodificación. 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).
Mensajes de error

Cuando el geocodificador devuelve un código de estado diferente de OK, posiblemente haya un campo error_message en el objeto de respuesta de geocodificación. Este campo contiene información más detallada acerca de los motivos del código de estado proporcionado.

Geocoder Asistido


Nuevo buscador de calles mejor Google Maps ingresen a www.guiacalles.pe para ubicar sus direcciones. Es el mejor buscador de direcciones, ya que cuenta con calles, cuadras, urbanizaciones, manzanas y lugares de interés.


Geocoder Batch


Ubica de manera masiva a todos tus clientes, puntos de interés.