Antes de empezar
La geocodificación convierte una dirección en coordenadas geográficas que son útiles para colocar marcadores en los mapas o localizar direcciones. Por ejemplo, al convertir «Rockefeller Center, Nueva York, EE. UU.», se obtiene una latitud de 40.7587402 y una longitud de 73.9786736.
Del mismo modo, la geocodificación inversa convierte las coordenadas geográficas en una dirección legible.
Cómo usar la API de geocodificación
El servicio de geocodificación Distancematrix.ai está disponible mediante un Interfaz HTTP para una variedad de aplicaciones, incluidos navegadores web, Postman e integración directa de aplicaciones. Los usuarios pueden enviar solicitudes de geocodificación estándar con una dirección o solicitudes de geocodificación inversa con coordenadas (latitud y longitud). El servicio le permite configurar aún más las solicitudes especificando parámetros adicionales con opciones de personalización.
Tras enviar su solicitud, el servicio responde con un Con formato JSON documento que contiene los resultados más relevantes, idealmente estructurado para un uso sencillo y la integración con varias plataformas, desde navegadores web hasta diferentes tipos de aplicaciones.
La seguridad es importante y se recomienda HTTPS siempre que sea posible, especialmente para las aplicaciones que incluyen datos confidenciales del usuario, como la ubicación del usuario, en las solicitudes. El uso del cifrado HTTPS hace que la aplicación sea más segura y resistente a la intromisión o la manipulación.
A continuación, encontrará ejemplos que muestran cómo hacer solicitudes e interpretar las respuestas, e ilustran el proceso para diferentes plataformas y métodos, incluidos los navegadores, Postman y la codificación basada en aplicaciones.
Cómo usar la API de geocodificación a través de Postman
Nuestra API es un servicio HTTP versátil adecuado para varios casos de uso y escenarios de integración. Se puede usar de cualquier forma que se adapte a sus necesidades, incluidas las solicitudes directas del navegador, la codificación en diferentes lenguajes de programación o la integración con aplicaciones y sistemas.
Una de las maneras más fáciles y eficientes de empezar a interactuar e integrar nuestra API en sus proyectos es usar
Cartero, conocida por su interfaz fácil de usar y sus potentes funciones.
He aquí cómo hacerlo:
Para empezar con Postman, instálalo en tu ordenador o accede a la versión web de un navegador.
Importe nuestra colección de API preconfigurada:
Tras la importación, Postman añadirá automáticamente la colección a tu espacio de trabajo.
Para los usuarios de la versión en línea de Postman, pueden abrir directamente el enlace de la colección y crear una bifurcación. Para ello, haga clic en los tres puntos situados junto al nombre de la colección.
Configure su entorno en Postman, vaya a la sección Variables y añada su token de autenticación en el campo «Token de autorización de API».
No olvides guardar estos cambios.
Haga su primera solicitud: seleccione un punto final de nuestra colección, configure los parámetros de su solicitud y pulse enviar para ver la respuesta.
-min.webp)
Tenga en cuenta que puede obtener su token individual en el panel de administración. Lee cómo hacerlo en
el artículo.
-min.webp)
No olvides guardar estos cambios.
-min.webp)
En nuestra colección Postman, encontrará todos los puntos finales, los tipos de solicitudes y los parámetros disponibles. En general, recomendamos utilizar solicitudes sincrónicas. Sin embargo, en situaciones en las que necesites procesar solicitudes masivas con un gran número de ubicaciones de una sola vez, las solicitudes asincrónicas también están disponibles y pueden ser efectivas. Para trabajar con ellas, haz clic en Distancematrix Accurate → Solicitudes masivas → Enviar un trabajo → Cuerpo, ¡empieza a trabajar!
-min.webp)
En la colección Postman, puedes encontrar todos los parámetros que necesitas para configurar tus solicitudes. Si tienes alguna pregunta, no dudes en
contacta con nosotros.
Cuando te sientas cómodo con lo básico, puedes explorar las funciones más avanzadas de nuestra API. La documentación detallada que aparece a continuación lo guiará a través de las funcionalidades específicas de nuestra API.
Guía para desarrolladores
A continuación, puedes leer cómo obtener la latitud y la longitud en la API de direcciones. Descubrirá qué parámetros obligatorios y opcionales debe usar y qué respuesta de geocodificación obtiene. Además, le mostraremos un ejemplo de respuesta JSON basada en la marca de salida.
Formato de solicitud de la API de geocodificación
La solicitud de la API de geocodificación se ha diseñado específicamente para parecerse al formato de solicitud que se usa con frecuencia y facilitar la transición desde servicios alternativos.
Una solicitud de la API de geocodificación tiene el siguiente aspecto:
OBTENER:
URL base: En el servicio de geocodificación DistanceMatrix.ai, las solicitudes se estructuran como direcciones URL con parámetros obligatorios y opcionales, separados por el signo de unión (&). Utilice el cifrado HTTPS por motivos de seguridad: https://.
Dominio: El dominio exacto de la API DistanceMatrix.ai es api-v2.distancematrix.ai
URL de solicitud: Para la geocodificación, es /maps/api/geocode/json.
Parámetros: Los parámetros son datos adicionales que se agregan a la URL de la solicitud para proporcionar detalles específicos a la API. Estos parámetros se pueden clasificar en dos tipos: obligatorios y opcionales.
Parámetros requeridos son obligatorios para que la API procese correctamente la solicitud porque proporcionan información esencial sin la cual la API no puede realizar la operación prevista. Por lo tanto, en una solicitud de la API de geocodificación, la dirección para la que necesita las coordenadas geográficas es un parámetro obligatorio. Sin esta dirección, la API no sabría qué ubicación geocodificar. Por ejemplo, para un lugar de interés como la Casa de Ana Frank ?address=Westermarkt+20,+1016+GV+Amsterdam,+Netherlands especifica la dirección para la geocodificación estándar.
Parámetros opcionales no son obligatorios, pero se pueden incluir para refinar o personalizar la respuesta de la API. Los parámetros opcionales pueden proporcionar un control adicional sobre el formato de la respuesta de la API, el idioma en el que se devuelven los datos u otros detalles relevantes para la solicitud. Por ejemplo, en una solicitud de geocodificación, un parámetro opcional puede ser el idioma en el que desea que se devuelvan los resultados, como &language=Reino Unido para especificar una preferencia de idioma. No es necesario incluir este parámetro para la función de geocodificación en sí, pero puede mejorar la usabilidad de los datos.
Token de autorización: Incluya su token de acceso único como &key=<your_access_token> para autenticar la solicitud.
Un ejemplo de una solicitud completa podría tener este aspecto:
https://api-v2.distancematrix.ai/maps/api/geocode/json?address=Westermarkt%2020,%201016%20GV%20Amsterdam,%20Netherlands&key=<your_access_token>
Respuestas de geocodificación
Nuestra API Geo convierte las direcciones en coordenadas (latitud y longitud). Devuelve las respuestas en el formato especificado en la solicitud de URL, como JSON. En el ejemplo siguiente, una solicitud de «1600 Amphitheatre Parkway, Mountain View, CA» utiliza el formato JSON para su respuesta, tal y como indica el indicador de salida JSON de la solicitud:
OBTENER:
https://api-v2.distancematrix.ai/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=<your_access_token>
El ejemplo de respuesta de JSON:
CUERPO
{
"result": [
{
"address_components": [
{
"long_name": "United States",
"short_name": "US",
"types": [
"country",
"political"
]
},
{
"long_name": "Mountain View",
"short_name": "Mountain View",
"types": [
"administrative_area_level_3",
"political"
]
},
{
"long_name": "94043",
"short_name": "94043",
"types": [
"postal_code"
]
},
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "Amphitheatre Parkway",
"short_name": "Amphitheatre Parkway",
"types": [
"route"
]
},
{
"long_name": "Google Headquarters",
"short_name": "Google Headquarters",
"types": [
"name"
]
},
{
"long_name": "CA",
"short_name": "CA",
"types": [
"state",
"administrative_area_level_1",
"political"
]
}
],
"formatted_address": "1600 Amphitheatre Parkway, Mountain View 94043, United States",
"geometry": {
"location": {
"lat": 37.4217636,
"lng": -122.084614
},
"location_type": "APPROXIMATE",
"viewport": {
"northeast": {
"lat": 37.4217636,
"lng": -122.084614
},
"southwest": {
"lat": 37.4217636,
"lng": -122.084614
}
}
},
"place_id": "2192620021",
"plus_code": {},
"types": [
"street_address"
]
}
],
"status": "OK"
}
Tenga en cuenta que la respuesta JSON contiene dos elementos raíz:
Los «resultados» contienen una serie de información de direcciones geocodificadas e información geométrica.
Por lo general, solo se devuelve una entrada de la matriz de «resultados» para las búsquedas de direcciones, aunque el geocodificador puede devolver varios resultados cuando las consultas de direcciones son ambiguas.
Tenga en cuenta que, por lo general, es necesario analizar estos resultados si desea extraer valores de los resultados.
Códigos de estado
El campo «estado» de la respuesta de geocodificación proporciona el estado de la solicitud y la información de depuración para ayudar a diagnosticar los problemas. Entre los posibles valores de estado se incluyen los siguientes:
«Aceptar»: la solicitud se ha realizado correctamente y se devuelven los datos de geocodificación.
«ZERO_RESULTS»: la geocodificación se realizó correctamente pero no arrojó ningún resultado, posiblemente debido a que no existía una dirección.
«OVER_DAILY_LIMIT»: esto puede significar que falta una clave de API o no es válida, que la cuenta no se factura o que se ha superado el límite de uso.
«OVER_QUERY_LIMIT»: Tu uso ha superado la cuota.
«REQUEST_DENIED»: se rechazó la solicitud.
«INVALID_REQUEST»: a menudo significa que falta una consulta (dirección, componentes o latlng).
«UNKNOWN_ERROR»: se produjo un error en el servidor; es posible que el reintento se realice correctamente.
Mensajes de error
Si el código de estado devuelto por el geocodificador no es «correcto», es posible que aparezca un campo opcional «error_message» en la respuesta. Este campo proporciona más detalles sobre por qué se devolvió ese código de estado en particular.
*Nota: Es posible que el campo «error_message» no esté siempre disponible y su contenido puede cambiar.
Resultados
Cuando el geocodificador devuelve resultados, se colocan en una matriz de resultados en formato JSON. Si no se encuentran resultados (por ejemplo, para una dirección que no existe), la matriz estará vacía.
Los campos típicos de un resultado incluyen:
matriz de tipos []: Especifica el tipo de resultado, con etiquetas como «localidad» para las ciudades o «político» para las entidades políticas. Por ejemplo, «Chicago» podría etiquetarse como ambas cosas.
dirección_formateada: Una cadena de direcciones legible por humanos, a menudo similar a una dirección postal. Sin embargo, en algunos lugares, como el Reino Unido, es posible que las direcciones postales verdaderas no se puedan distribuir. Esta dirección se compone de componentes como el número de la calle, la ruta, la ciudad y el estado. En lugar de analizar esta dirección, utilice los componentes de dirección independientes que también se proporcionan en la respuesta.
direcciones_componentes []: Una matriz de los componentes de la dirección.
Cada componente de dirección normalmente contiene los siguientes campos:
tipos []: Especifica el tipo de cada componente de dirección.
nombre_largo: Proporciona el texto completo de la descripción o el nombre del componente de dirección tal como lo indica el geocodificador.
nombre_corto: Se aplica al nombre del componente de dirección con una versión abreviada disponible del nombre del componente de dirección. Tomemos el estado de Alaska como ejemplo: a nombre_corto de «AK», que es su abreviatura postal de 2 letras y un nombre_largo de «Alaska».
Estos son algunos datos más sobre la componentes de direcciones [] matriz a tener en cuenta:
El componentes de direcciones [] La matriz de una respuesta de geocodificación puede tener más elementos que la formatted_address.
No siempre incluye a todas las entidades políticas que contienen la dirección, excepto las que figuran en dirección_formateada. Para obtener una lista completa, utilice la geocodificación inversa con la latitud/longitud de la dirección.
El formato de respuesta, incluidos el número y los tipos de componentes de la dirección, puede variar entre las solicitudes y a lo largo del tiempo para la misma dirección. Los componentes pueden cambiar de posición o tipo o pueden omitirse en las respuestas posteriores.
Para utilizar eficazmente la respuesta del geocodificador, debe analizar la matriz de componentes:
localidad_código postal []: Esta matriz muestra todas las localidades de un código postal. Aparece solo para los códigos postales que abarcan varias localidades.
geometría: Incluye información clave como:
coincidencia parcial: indica una coincidencia no exacta con la solicitud, lo que resulta útil para identificar posibles problemas, como errores ortográficos o direcciones incompletas. Las coincidencias parciales suelen producirse con direcciones postales inexistentes o cuando una dirección coincide con varias ubicaciones de la misma zona. Por ejemplo, una dirección mal escrita (supongamos que es «21 Henry St, Bristol, Reino Unido») puede arrojar una calle con un sonido similar como resultado de una coincidencia parcial («Henry Street» y «Henrietta Street»).
Tipos de direcciones y tipos de componentes de direcciones
El tipos [] La matriz del resultado de la geocodificación especifica el tipo de dirección, como una dirección postal, un país o una entidad política. También hay un tipos [] matriz dentro componentes de direcciones [] que especifica el tipo de cada parte de la dirección, como el número de la calle o el país. Las direcciones pueden ser de varios tipos y funcionar como «etiquetas». Por ejemplo, las ciudades suelen tener etiquetas como «política» y «localidad».
El geocodificador admite y devuelve varios tipos en matrices de tipos de direcciones y tipos de componentes:
dirección_calle: Una dirección postal precisa.
recorrido: Una ruta con nombre como «US 101".
intersección: Una intersección importante de dos carreteras principales.
político: Entidad política, que normalmente indica un polígono de administración civil.
país: La entidad política nacional, con frecuencia del tipo más alto.
área_administrativo_nivel_1: Una entidad civil primaria por debajo del nivel del país, como los estados de EE. UU. Estas suelen alinearse con las subdivisiones de la ISO 3166-2.
nivel_de_área_administrativo_2: Una entidad civil secundaria, como los condados de EE. UU.
nivel_de_área_administrativo_3/nivel_de_área_administrativa_nivel_5: Entidades civiles de orden inferior, que representan divisiones menores.
área_coloquial: Nombre alternativo de uso común para la entidad.
localidad: Una ciudad o pueblo incorporado.
sublocalidad (y niveles 1-5: sublocality_level_1 a sublocality_level_5): entidades de orden inferior dentro de una localidad. Cuanto menor sea el área geográfica, mayores serán los números.
barrio: Un barrio con nombre.
premisa: Una ubicación con nombre, normalmente un edificio o complejo.
premisa secundaria: Parte de un local más grande, como un edificio dentro de un complejo.
código_postal: Un código postal utilizado en el país.
característica_natural: Una característica natural importante.
aeropuerto: Un aeropuerto.
parque: Un parque con nombre.
punto_de_interés: Una entidad prominente como el «Empire State Building» o la «Torre Eiffel».
Si la lista de tipos de un componente de dirección está vacía, significa que no se conocen tipos específicos para ese componente, como un «Lieu-dit» en Francia. Además, los componentes de direcciones pueden incluir:
planta: El número de planta de un edificio.
establecimiento: Un lugar aún no categorizado.
punto_de_interés: Un punto de interés con nombre.
estacionamiento: Un estacionamiento o estructura.
buzón de correo: Un buzón postal específico.
ciudad_postal: Agrupación de áreas geográficas que se usa para las direcciones postales en algunos países.
habitación: Una habitación en un edificio.
número_calle: El número exacto de la calle.
estación de autobús, estación de tren, estación de tránsito: Ubicaciones de paradas de autobús, tren o transporte público.
PREGUNTAS MÁS FRECUENTES
¿Qué diferencia a esta API de otras API de geocodificación?
La API de geocodificación de Distancematrix.ai tiene varios factores que la diferencian de otras API de geocodificación:
Alta precisión: la API de geocodificación de Distancematrix.ai utiliza algoritmos y fuentes de datos avanzados para proporcionar resultados de geocodificación precisos y fiables. La API también tiene una alta tasa de éxito a la hora de hacer coincidir direcciones, lo que significa que puede gestionar una amplia gama de formatos y variaciones de direcciones.
Cobertura global: la API cubre una amplia gama de países y regiones, incluidos lugares de difícil acceso como áreas rurales, islas y países en desarrollo. Esto significa que los usuarios pueden confiar en la API para obtener resultados precisos sin importar de dónde provengan sus datos.
Velocidad y escalabilidad: la API está diseñada para gestionar grandes volúmenes de solicitudes de geocodificación de forma rápida y eficiente.
Rentable: la API ofrece un modelo de precios simple y transparente, sin comisiones ocultas ni costes iniciales. La API ofrece un plan gratuito y un plan de crecimiento con un modelo de precios de pago por uso.
¿Puedo usar esta API como dirección de conversión a una API de última duración?
Sí, puede usar la API de geocodificación Distancematrix.ai para convertir direcciones en coordenadas de latitud y longitud. De hecho, esa es una de las funciones principales de una API de direcciones que duran mucho como esta.
Para usar la API para la geocodificación, debe enviar una solicitud a la API con un parámetro de dirección y la API responderá con las coordenadas lat-long correspondientes a esa dirección.
La API de geocodificación de Distancematrix.ai está diseñada como una API de obtención de latitud y longitud a partir de direcciones que es fácil de usar. Se puede integrar en una amplia gama de aplicaciones y plataformas. La API admite una variedad de lenguajes y marcos de programación, incluidos Python, JavaScript y PHP, entre otros.
¿Puedo usar esta API como un conversor de API de latitud y longitud para direcciones legibles por humanos?
Sí, puede usar la API de geocodificación Distancematrix.ai para convertir las coordenadas de latitud y longitud (lat-long) en direcciones legibles por humanos. Este proceso también se conoce como geocodificación inversa y los desarrolladores suelen buscar una API de latitud y longitud o una API de obtención de coordenadas a partir de la API de direcciones.
Para usar la API para la geocodificación inversa, debe enviar una solicitud a la API con los parámetros de latitud y longitud, y la API responderá con la dirección correspondiente legible por humanos para esas coordenadas.
Si tiene alguna pregunta o necesita más ayuda para usar la API para sus necesidades de geocodificación inversa, el equipo de Distancematrix.ai proporciona documentación detallada y asistencia al cliente para ayudarle a empezar.
¿Qué puede hacer con la API de geocodificación?
Muchas empresas y empresas utilizan software y aplicaciones para localizar tiendas, almacenes, vehículos y clientes, a fin de controlar el transporte y los movimientos relacionados con la geocodificación. Sin embargo, en la actualidad, su definición no se limita a las búsquedas de direcciones. Es una herramienta bastante universal que permite aplicarla al mercado en general, desde la ubicación precisa y la cartografía de rutas hasta el análisis de los datos de los clientes y el reconocimiento de patrones geográficos.
Esta solución es útil, por ejemplo, para los taxistas en caso de que carezcan de datos precisos sobre las direcciones de destino de los clientes. Además, este servicio es práctico para los repartidores de comida a domicilio en sus rutinas diarias. Puede leer otros ejemplos exitosos de API de geocodificación utilizando nuestro sitio web.
¿Por qué usar la API de geocodificación?
Las API de Distancematrix.ai ofrecen la mejor precisión de su clase que compite con los gigantes del sector, pero a un precio mucho más asequible, una mayor escalabilidad y un equipo de soporte humano amable y real que siempre está disponible para ayudarlo con sus preguntas. Una ventaja adicional es la facilidad de transición con respecto a otros proveedores, lo que garantiza un proceso de cambio sin problemas.
Además, Distancematrix.ai permite a los usuarios probar el servicio sin necesidad de adjuntar una tarjeta de crédito/débito antes de tomar una decisión final. Esto se hace para que los usuarios puedan verificar la calidad y el valor de los resultados obtenidos. No dude en intentar asegurarse de que Distancematrix.ai sea una solución de alta calidad, rápida y rentable. Además, incluso durante el período de prueba, los usuarios pueden ponerse en contacto con el soporte en vivo disponible para cualquier consulta.
