Documentación

# ¿Qué es Geocoding?

Geocoding es el proceso de conversión de direcciones como ("Jr Pedro Ruiz 668, Breña, Lima, PE") en coordenadas geográficas como (latitud -12.065819 y longitud -77.054538), que puede utilizar para colocar marcadores en un mapa o colocar el mapa.

Reverse geocoding es el proceso de convertir coordenadas geográficas en una dirección legible por humanos.

La API de Geocoding proporciona una forma directa de acceder a estos servicios a través de una solicitud HTTP.

# Importante

Este documento describe el servicio web API de Geocoding. Está destinado a desarrolladores de sitios web y dispositivos móviles que desean utilizar datos de Geocoding en mapas proporcionados por una de las API de la plataforma Geodir.

Nota: Este servicio generalmente está diseñado para geocodificar direcciones estáticas (conocidas de antemano) para colocar el contenido de la aplicación en un mapa; este servicio no está diseñado para responder en tiempo real a las entradas del usuario.

Antes de comenzar a desarrollar con la API de Geocoding, revise los requisitos de autenticación (necesita una clave de API) y la información de precios de la API.

# Formato de Solicitud de API de Geocoding

Una solicitud de API de Geocoding tiene la siguiente forma:

https://apis.geodir.co/geocoding/v1/outputFormat?parameters

donde outputFormat puede ser cualquiera de los siguientes valores:

  • json (recomendado) indica la salida en notación de objetos JavaScript (JSON); o
  • xml indica salida en XML

La seguridad es importante y se recomienda HTTPS siempre que sea posible, especialmente para aplicaciones que incluyen datos confidenciales del usuario, como la ubicación de un usuario, en las solicitudes. El uso de la encriptación HTTPS hace que su aplicación sea más segura y más resistente a espionaje o manipulación.

Nota: Las URL deben estar codificadas correctamente (Consulte las mejores prácticas) para que sean válidas y están limitadas a 8000 caracteres para todos los servicios web. Tenga en cuenta este límite al crear sus URL. Tenga en cuenta que los diferentes navegadores, proxies y servidores también pueden tener diferentes límites de caracteres de URL.

Algunos parámetros son obligatorios mientras que otros son opcionales. Como es estándar en las URL, los parámetros se separan mediante el carácter comercial (&).

# Geocoding (Búsqueda de Latitud / Longitud)

Parámetros obligatorios en una solicitud de Geocoding:

  • address: especifique las direcciones de acuerdo con el formato utilizado por el servicio postal nacional del país en cuestión. Deben evitarse elementos de dirección adicionales, como nombres comerciales y números de unidad, suite o piso. Los elementos de la dirección postal deben estar delimitados por espacios (que se muestran aquí como URL de escape a% 20):

    address=Jiron%20Pedro%20Ruiz%20Gallo%20668
  • key: la clave API de su aplicación. Esta clave identifica su aplicación a los efectos de la gestión de cuotas. Aprenda a obtener su clave API.

Parámetros opcionales en una solicitud de Geocoding:

  • segments: es un filtro con elementos separados por una tubería (|). El filtro de segmentos también se acepta como parámetro opcional si se proporciona una dirección. Cada elemento consta de un par segmento lo cual es un valor y restringe completamente los resultados del geocodificador. Consulte más información sobre el filtrado de segmentos.

# Respuestas de Geocoding

Las respuestas de Geocoding se devuelven en el formato indicado por la marca output dentro de la ruta de la solicitud de URL.

En este ejemplo, la API de Geocoding solicita una respuesta json para una consulta sobre "Jr Pedro Ruiz Gallo 668, Breña, Lima, PE".

Esta solicitud demuestra el uso de la marca de output JSON:

https://apis.geodir.co/geocoding/v1/json?address=jr pedro ruiz gallo nro 668&segments=locality_id:150105&key=YOUR_KEY

Vea a continuación las respuestas JSON de muestra.

{
    "status": "OK",
    "results": [
        {
            "result_types": [
                "address"
            ],
            "address_segments": [
                {
                    "name": "668",
                    "name_abbr": "668",
                    "types": [
                        "route_number"
                    ]
                },
                {
                    "name": "Pedro Ruiz Gallo",
                    "name_abbr": "Pedro Ruiz Gallo",
                    "types": [
                        "route"
                    ]
                },
                {
                    "name": "Jirón",
                    "name_abbr": "Jr",
                    "types": [
                        "route_type"
                    ]
                },
                {
                    "name": "Lima",
                    "name_abbr": "Lima",
                    "types": [
                        "admin_level_1",
                        "political"
                    ]
                },
                {
                    "name": "15",
                    "name_abbr": "15",
                    "types": [
                        "admin_level_1_code",
                        "political"
                    ]
                },
                {
                    "name": "Lima",
                    "name_abbr": "Lima",
                    "types": [
                        "admin_level_2",
                        "political"
                    ]
                },
                {
                    "name": "1501",
                    "name_abbr": "1501",
                    "types": [
                        "admin_level_2_code",
                        "political"
                    ]
                },
                {
                    "name": "Breña",
                    "name_abbr": "Breña",
                    "types": [
                        "admin_level_3",
                        "political"
                    ]
                },
                {
                    "name": "150105",
                    "name_abbr": "150105",
                    "types": [
                        "admin_level_3_code",
                        "political"
                    ]
                },
                {
                    "name": "San Gregorio",
                    "name_abbr": "San Gregorio",
                    "types": [
                        "sublocality",
                        "political"
                    ]
                },
                {
                    "name": "Perú",
                    "name_abbr": "PE",
                    "types": [
                        "country",
                        "political"
                    ]
                },
                {
                    "name": "15083",
                    "name_abbr": "15083",
                    "types": [
                        "postal_code"
                    ]
                }
            ],
            "geometry": {
                "coordinates": {
                    "lat": -12.0658283,
                    "lon": -77.0546503
                },
                "bbox": [
                    -77.0546503,
                    -12.0658283,
                    -77.0546503,
                    -12.0658283
                ],
                "geocoding_type": "INTERPOLATED"
            },
            "place_id": "407779ce754bbb738c285742a8528fea55",
            "standard_address": "Jirón Pedro Ruiz Gallo 668, Breña, Lima, Perú"
        }
    ]
}

Tenga en cuenta que la respuesta JSON contiene dos elementos raíz:

  • "status" contiene metadatos sobre la solicitud. Consulte los Status Codes a continuación.
  • "results" contiene una serie de información de dirección geocodificada e información de geometría.

Generalmente, solo se devuelve una entrada en la matriz de "results" para las búsquedas de direcciones, aunque el geocodificador puede devolver varios resultados cuando las consultas de direcciones son ambiguas.

Nota: Tenga en cuenta que estos resultados generalmente deben analizarse si desea extraer valores de los resultados. Analizar JSON es relativamente fácil. Consulte análisis de JSON para conocer algunos patrones de diseño recomendados.

# Códigos de Estado

El campo "status" dentro del objeto de respuesta de Geocoding contiene el estado de la solicitud y puede contener información de depuración para ayudarlo a averiguar por qué Geocoding no funciona. El campo "status" puede contener los siguientes valores:

  • "OK" indica que no se produjeron errores; la dirección se analizó correctamente y se devolvió al menos un código geográfico.
  • "ZERO_RESULTS" indica que el código geográfico se realizó correctamente pero no arrojó resultados. Esto puede ocurrir si al geocodificador se le pasó un address inexistente.
  • OVER_DAILY_LIMIT indica cualquiera de los siguientes:
    • Falta la clave API o no es válida.
    • No se ha habilitado la facturación en su cuenta.
    • Se superó un límite de uso impuesto en blanco.
    • El método de pago proporcionado ya no es válido (por ejemplo, una tarjeta de crédito ha caducado).
  • "OVER_QUERY_LIMIT" indica que ha superado su cuota.
  • "REQUEST_DENIED" indica que su solicitud fue denegada.
  • "INVALID_REQUEST" generalmente indica que falta la consulta (address, segments o latlon).
  • "UNKNOWN_ERROR" indica que la solicitud no se pudo procesar debido a un error del servidor. La solicitud puede tener éxito si vuelve a intentarlo.

# Resultados

Cuando el geocodificador devuelve resultados, los coloca dentro de una matriz de resultados (JSON). Incluso si el geocodificador no devuelve resultados (por ejemplo, si la dirección no existe), todavía devuelve una matriz de resultados vacía. (Las respuestas XML constan de cero o más elementos de resultado).

Un resultado típico contiene los siguientes campos:

  • result_types[] indica el tipo de resultado devuelto. Esta matriz contiene un conjunto de cero o más etiquetas que identifican el tipo de característica devuelta en el resultado. Por ejemplo, un código geográfico de "Breña" devuelve "localidad", que indica que "Breña" es una ciudad, y también devuelve "político", que indica que es una entidad política.

  • standard_address es una cadena que contiene la dirección legible por humanos de esta ubicación.

A menudo, esta dirección es equivalente a la dirección postal.

El standard_address se compone lógicamente de uno o más address_segments[]. Por ejemplo, la dirección "Jr Pedro Ruiz Gallo 668, Breña, Lima, PE" consta de los siguientes segmentos: "668" (el número de la calle), "Jr Pedro Ruiz Gallo" (la ruta), "Breña" (la ciudad ) y "PE" (el país).

No analice el standard_address mediante programación. En su lugar, debe utilizar los address_segments[] individuales, que la respuesta de la API incluye además del campo standard_address.

  • address_segments[] es una matriz que contiene los segmentos separados aplicables a esta dirección.

    Cada segmento de dirección normalmente contiene los siguientes campos:

    • types[] es una matriz que indica el de los segmentos de dirección. Consulte la lista de tipos admitidos.

    • name es la descripción de texto completo o el nombre del segmento de dirección como lo devuelve el Geocoding.

    • name_abbr es un nombre textual abreviado para el segmento de dirección, si está disponible. Por ejemplo, un segmento de dirección para el país de Perú puede tener un name de "Peru" y un name_abbr de "PE" usando la abreviatura de 2 letras.

    Tenga en cuenta los siguientes datos sobre la matriz address_segments[]:

    • La matriz de segmentos de dirección puede contener más segmentos que standard_address.
    • La matriz no incluye necesariamente todas las entidades políticas que contienen una dirección, aparte de las incluidas en standard_address. Para recuperar todas las entidades políticas que contienen una dirección específica, debe utilizar Geocoding Reverse, pasando la latitud / longitud de la dirección como parámetro a la solicitud.
    • No se garantiza que el formato de la respuesta siga siendo el mismo entre solicitudes. En particular, el número de address_segments varía según la dirección solicitada y puede cambiar con el tiempo para la misma dirección. Un segmento puede cambiar de posición en la matriz. El tipo de segmento puede cambiar. Es posible que falte un segmento en particular en una respuesta posterior.

    Para manejar la matriz de segmentos, debe analizar la respuesta y seleccionar los valores apropiados mediante expresiones. Consulte la guía para analizar una respuesta.

  • geometry contiene la siguiente información:

    • coordinates contiene la latitud geocodificada, el valor de longitud. Para las búsquedas de direcciones normales, este campo suele ser el más importante.
    • geocoding_type almacena datos adicionales sobre la ubicación especificada. Actualmente se admiten los siguientes valores:
      • "DOOR" indica que el resultado devuelto es un código geográfico preciso para el que tenemos información de ubicación precisa hasta la precisión de la puerta.
      • "INTERPOLATED" indica que el resultado devuelto refleja una aproximación (generalmente en una carretera) interpolada entre dos puntos precisos (como intersecciones). Los resultados interpolados generalmente se devuelven cuando el nivel DOOR no está disponible para la dirección.
      • "CENTER" indica que el resultado devuelto es el centro geométrico de un resultado como una polilínea (por ejemplo, una calle) o un polígono (región).
      • "APROXIMATE" indica que el resultado devuelto es aproximado. Para obtener más detalles, revise los Types y Subtypes de Geocoding.
    • bbox contiene la ventana gráfica recomendada para mostrar el resultado devuelto, especificado como dos valores de latitud y longitud del cuadro delimitador.

  • place_id es un identificador único que se puede utilizar con otras API de Geodir. Por ejemplo, puede usar place_id en un Place API solicite obtener detalles de una empresa local, como el número de teléfono, el horario de atención y más. Ver place ID.

# Tipos de Direcciones y Segmentos

La matriz de types[] en el resultado indica el tipo de dirección. Los ejemplos de tipos de direcciones incluyen una dirección postal, un país o una entidad política. También hay una matriz de types[] en el address_segments[], que indica el tipo de cada parte de la dirección. Los ejemplos incluyen el número de la calle o el país. (A continuación se muestra una lista completa de tipos). Las direcciones pueden tener varios tipos. Los tipos pueden considerarse "etiquetas". Por ejemplo, muchas ciudades están etiquetadas con el tipo political y locality.

Los siguientes tipos son compatibles y devueltos por el geocodificador tanto en el tipo de dirección como en las matrices de tipo de segmento de dirección:

  • route indica una ruta con nombre (como "Av Arequipa").
  • crossing indica una intersección principal, generalmente de dos carreteras principales.
  • political indica una entidad política. Por lo general, este tipo indica un polígono de alguna administración civil.
  • country indica la entidad política nacional y suele ser el tipo de orden más alto devuelto por el Geocoding.
  • admin_level_1 indica una entidad civil de primer orden por debajo del nivel de país. Dentro del Perú, estos niveles administrativos son departamentos. No todas las naciones exhiben estos niveles administrativos. En la mayoría de los casos, los nombres cortos admin_level_1 coincidirán estrechamente con las subdivisiones ISO 3166-2 y otras listas de amplia circulación; sin embargo, esto no está garantizado ya que nuestros resultados de Geocoding se basan en una variedad de señales y datos de ubicación.
  • admin_level_2 indica una entidad civil de segundo orden por debajo del nivel del país. Dentro del Perú, estos niveles administrativos son provincias. No todas las naciones exhiben estos niveles administrativos.
  • admin_level_3 indica una entidad civil de tercer orden por debajo del nivel de país. Este tipo indica una división civil menor. No todas las naciones exhiben estos niveles administrativos.
  • admin_level_4 indica una entidad civil de cuarto orden por debajo del nivel de país. Este tipo indica una división civil menor. No todas las naciones exhiben estos niveles administrativos.
  • admin_level_5 indica una entidad civil de quinto orden por debajo del nivel de país. Este tipo indica una división civil menor. No todas las naciones exhiben estos niveles administrativos.
  • common_area indica un nombre alternativo de uso común para la entidad.
  • locality indica una entidad política incorporada de una ciudad o pueblo. Dentro del Perú, estas localidades son distritos.
  • locality_id indica un código incorporado por entidad política de ciudad o pueblo. Dentro del Perú, estos locality_id son ubigeo, por ejemplo 150105 para "Breña".
  • sublocality indica una entidad civil de primer orden debajo de una localidad. Para algunas ubicaciones, puede recibir uno de los tipos adicionales: sublocality_level_1 a sublocality_level_5. Cada nivel de sublocalidad es una entidad civil. Los números más grandes indican un área geográfica más pequeña. Dentro del Perú, estas sublocality son nucleo urbano (urbanización), por ejemplo "Urb San Gregorio".
  • neighborhood indica un vecindario con nombre.
  • premise indica una ubicación con nombre, generalmente un edificio o una colección de edificios con un nombre común. Dentro del Perú, estas premise son condominio, por ejemplo "Res San Felipe".
  • subpremise indica una entidad de primer orden debajo de una ubicación con nombre, generalmente un edificio singular dentro de una colección de edificios con un nombre común.
  • postal_code indica un código postal que se utiliza para dirigir el correo postal dentro del país.
  • natural_feature indica una característica natural prominente.
  • airport indica un aeropuerto.
  • park indica un parque con nombre.
  • poi indica un punto de interés con nombre. Por lo general, estos poi son entidades locales prominentes que no encajan fácilmente en otra categoría, como "Plaza Norte" o "Macchupicchu".

Una lista vacía de tipos indica que no hay tipos conocidos para el segmento de dirección en particular, por ejemplo, Machupicchu en Perú.

Además de lo anterior, los segmentos de dirección pueden incluir los tipos siguientes:

  • floor indica el piso de la dirección de un edificio.
  • establishment generalmente indica un lugar que aún no ha sido categorizado.
  • poi indica un punto de interés con nombre.
  • parking indica un estacionamiento o estructura de estacionamiento.
  • post_box indica una casilla postal específica.
  • postal_town indica una agrupación de áreas geográficas, como locality y sublocality, que se utiliza para direcciones de correo en algunos países.
  • room indica la habitación de la dirección de un edificio.
  • route_number indica el número exacto de la calle.
  • bus_station, train_station y transit_station indican la ubicación de una parada de autobús, tren o transporte público.

# Filtrado de Segmentos

En una respuesta de Geocoding, la API de Geocoding puede devolver resultados de direcciones restringidos a un área específica. Puede especificar la restricción utilizando el filtro de segments. Un filtro consta de una lista de pares segment:value separados por una barra vertical (|). Los valores de filtro admiten los mismos métodos de corrección ortográfica y coincidencia parcial que otras solicitudes de Geocoding.

Los siguientes segments pueden usarse para influir en los resultados, pero no se aplicarán:

  • locality coincide con tipos locality y sublocality.

Notas sobre el filtrado de segmentos:

  • Los resultados son consistentes con Geodir Maps, que ocasionalmente produce respuestas ZERO_RESULTS. El uso de Places Autocomplete puede proporcionar mejores resultados en algunos casos de uso.
  • Para cada segmento de dirección, especifíquelo en el parámetro de address o en un segments, pero no en ambos. Especificar los mismos valores en ambos puede resultar en ZERO_RESULTS.

Un código geográfico para "Av Arequipa" con segments=locality_id:150116 devuelve un resultado en Lince, Perú, en lugar de Miraflores, Perú. Pedido:

https://apis.geodir.co/geocoding/v1/json?address=Av Arequipa&segments=locality_id:150116&key=YOUR_KEY
Ultima actualizacion: 03/10/2023, 10:32:10 a. m.

Reverse Geocoding →