Antes de empezar
Las API de geocodificación convierten 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
Las API de geocodificación de Distancematrix.ai están disponibles a través de una interfaz HTTP para una variedad de aplicaciones, incluidos los navegadores web, Postman y la 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.
Después de enviar su solicitud, el servicio responde con un documento con formato JSON 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 e instrucciones sobre las solicitudes HTTPS de nuestras API de geocodificación, adecuadas para una amplia gama de enfoques, ya sea a través de un navegador web, cualquier plataforma o aplicación de su elección o sistemas como Postman. Esta guía incluye descripciones exhaustivas sobre cómo formular solicitudes e interpretar las respuestas en diferentes entornos.
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 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 le guiará a través de las funcionalidades específicas de nuestra API.
Parámetros opcionales en una solicitud de geocodificación:
lengua — El idioma en el que se devolverán los resultados.
Consulta la lista de idiomas compatibles.
El geocodificador utiliza de forma predeterminada el idioma especificado en el encabezado Accept-Language o el idioma nativo del dominio de la solicitud si no se proporciona ningún idioma.
Para garantizar la legibilidad, el geocodificador devuelve las direcciones postales en el idioma local y utiliza la transliteración cuando es necesario, según el idioma preferido del usuario. Todos los componentes de la dirección se entregan en el mismo idioma, determinado por el idioma del primer componente.
Si el nombre de una dirección no está disponible en el idioma preferido, el geocodificador selecciona la coincidencia disponible más cercana.
El idioma preferido influye sutilmente en la selección y el orden de los resultados, ya que el geocodificador interpreta las abreviaturas y los sinónimos de forma diferente según el idioma. Por ejemplo, «utca» y «tér» en húngaro corresponden a «calle» y «plaza».
Mostrar idiomas
Ocultar idiomas
Código de idioma
Idioma
Código de idioma
Idioma
af
afrikáans
ja
japonés
m2
albanesa
kn
canarés
soy
amárico
kk
Kazajo
soy
árabe
km
Jemer
por qué
armenio
ko
coreano
az
Azerbaiyano
cielo
Kirguís
eu
vasco
lo
Lao
estar
Bielorruso
lv
letón
bn
bengalí
lt
lituano
bs
bosnio
km
macedónio
bolsa
búlgaro
ms
malayo
mi
birmano
ml
Malayalam
ca
catalán
señor
marathi
zh
chino
mn
mongol
zh-CN
Chino (simplificado)
nuevo
nepalés
zh-HK
Chino (Hong Kong)
no
noruego
zh-TW
Chino (tradicional)
pl
polaco
hora
croata
pt
portugués
cs
checa
pt-BR
Portugués (Brasil)
da
danés
pt-PT
Portugués (Portugal)
nl
holandesa
pa
panyabí
es
Inglés
o
rumano
en-AU
Inglés (australiano)
ru
rusa
en-GB
Inglés (Gran Bretaña)
sr
serbio
et
estonio
es
cingalés
fa
farsi
sk
eslovaco
fi
finlandés
sl
esloveno
filmar
filipino
sí
española
para
francesa
es-419
Español (Latinoamérica)
FR-CA
Francés (Canadá)
sw
swahili
gl
gallego
sv
sueco
ka
georgiano
té
Tamil
de
alemán
te
Telugu
el
griego
la
tailandés
pistola
Gujarati
tr
turca
es
hebreo
Reino Unido
ucraniana
hola
hindi
nuestro
Urdu
hu
húngara
nosotros
Uzbek
is
Icelandic
vi
Vietnamese
id
Indonesian
zu
Zulu
it
Italian
region — specified as a two-character ccTLD ("top-level domain") value, this parameter influences but does not strictly limit the geocoder's results.
Required parameters in a geocoding request:
address: Here you need to mention the street address for geocoding. It should be formatted as per the national postal service standards of the relevant country, excluding elements like business names or unit/suit/floor numbers. Use spaces (URL-escaped as %20) to separate street address elements, e.g.:
address=100%20Queens%20Park%20Toronto%20ON where "100 Queens Park, Toronto, ON" is the address of the Royal Ontario Museum
key: This parameter requires your unique API authorization token, which is necessary to verify the identity and permissions of the client making the request, ensuring secure access and accurate monitoring of its usage quota.
More details about the key, its purpose, obtaining process, and Geocoding API limits applied to the key, can be found at the
link.
Geocoding Responses
Our Geo API converts addresses to coordinates (latitude and longitude). It returns responses in the format specified in the URL request, such as JSON. In the example below, a request for “1600 Amphitheatre Parkway, Mountain View, CA” uses JSON format for its response, as indicated by the JSON output flag in the request:
GET:
https://api.distancematrix.ai/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=<your_access_token>
The sample JSON response:
BODY
{
"result": [
{
"address_components": [
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "amphitheatre parkway",
"short_name": "amphitheatre parkway",
"types": [
"route"
]
},
{
"long_name": "mountain view",
"short_name": "mountain view",
"types": [
"locality"
]
},
{
"long_name": "ca",
"short_name": "ca",
"types": [
"state"
]
}
],
"formatted_address": "1600 Amphitheatre Parkway, Mountain View, CA",
"geometry": {
"location": {
"lat": 37.422387799999996,
"lng": -122.08418770000002
},
"location_type": "APPROXIMATE",
"viewport": {
"northeast": {
"lat": 37.422387799999996,
"lng": -122.08418770000002
},
"southwest": {
"lat": 37.422387799999996,
"lng": -122.08418770000002
}
}
},
"place_id": "",
"plus_code": {
"compound_code": "CWC8+R9 Mountain View, California, United States",
"global_code": "849VCWC8+R9"
},
"types": [
"locality",
"political"
]
}
],
"status": "OK"
}
Note that the JSON response contains two root elements:
"status" contains metadata on the request. See
Status Codes below.
"results" contains an array of geocoded address information and geometry information.
Generally, only one entry in the "results" array is returned for address lookups,though the geocoder may return several results when address queries are ambiguous.
Note that these results generally need to be parsed if you wish to extract values from the results.
Status Codes
The "status" field in the Geocoding response gives the request status and debugging information to help diagnose issues. Possible status values include:
"OK": The request was successful, and geocoding data is returned.
"ZERO_RESULTS": Geocoding was successful but yielded no results, possibly due to a non-existent address.
"OVER_DAILY_LIMIT": This can mean an invalid or missing API key, no billing on the account, or a usage cap exceeded.
"OVER_QUERY_LIMIT": Your usage has exceeded the quota.
"REQUEST_DENIED": The request was denied.
"INVALID_REQUEST": Often means a missing query (address, components, or latlng).
"UNKNOWN_ERROR": A server error occurred; a retry may succeed.
Error Messages
If the status code returned by the Geocoder is not “OK”, an optional “error_message” field may appear in the response. This field provides more details about why that particular status code was returned.
*Note: The “error_message” field may not always be available, and its contents may change.
Results
When the geocoder returns results, they are placed in a results array in JSON format. If no results are found (such as for a non-existent address), the array will be empty.
Typical fields in a result include:
types[] array: Specifies the type of result, with tags like “locality” for cities or “political” for political entities. For example, “Chicago” could be tagged as both.
formatted_address: A human-readable address string, often similar to a postal address. However, in some places, such as the United Kingdom, true postal addresses may not be distributable. This address is made up of components such as the street number, route, city, and state. Instead of parsing this address, use the separate address components that are also provided in the response.
address_components[]: An array of the address components.
Each address component typically contains the following fields:
types[]: Specifies the type of each address component.
long_name: Provides the full text description or name of the address component as given by the Geocoder.
short_name: Applies to the address component's name with an available abbreviated version of the address component's name. Let's take the state of Alaska as an example: a short_name of "AK," which is its 2-letter postal abbreviation and a long_name of "Alaska".
Here are some more facts about the address_components[] array to keep in mind:
The address_components[] array in a geocoding response may have more elements than the formatted_address.
It doesn't always include all political entities containing the address, except those in the formatted_address. For a complete list, use reverse geocoding with the address's latitude/longitude.
The response format, including the number and types of address components, can vary between requests and over time for the same address. Components may change in position, type, or may be omitted in subsequent responses.
To effectively use the response from the geocoder, you need to parse the array of components:
postcode_localities[]: This array lists all localities within a postal code. It appears only for postal codes encompassing multiple localities.
geometry: Includes key information like:
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.
¿Qué es una API de geocodificación?
Una API de geocodificación es un servicio que convierte direcciones postales en coordenadas geográficas (latitud/longitud) y viceversa. Permite a las aplicaciones colocar ubicaciones en los mapas con precisión, calcular distancias entre puntos y realizar operaciones basadas en la ubicación.
