El propósito de este primer endpoint es devolver coordenadas geográficas de una dirección completa o parcia.

• Lista de parámetros
• Ejemplo 1 – Buscar coordenadas desde la dirección
• Ejemplo 2 – Búsqueda coordinada basada en código postal

Para realizar una solicitud a la API Geocode es necesario enviar la solicitud mediante el método POST al siguiente endpoint: 

• https://api.maplink.global/geocode/v2/geocode – POST

Nota: Actualmente regresa solo a direcciones ubicadas en Brasil.

La API Geocode se ha actualizado a V2. El enpoint https://api.maplink.global/geocode/v1/geocode seguirá funcionando, pero se recomienda utilizar el nuevo endpoint para obtener una mayor precisión de los resultados y porque las nuevas funciones serán exclusivas de la nueva versión.

Lista de parámetros

Parámetros obligatorios

Es obligatorio informar al menos a uno. No es necesario informar a todo el mundo. Sin embargo, cuanta más información proporcione, más preciso será el resultado.

• road – Nombre de la calle o parte de ella;
• number – Número de la calle. NO ingrese los datos del complemento;
• city – Nombre de la ciudad;
• state – Estado;
• country – País;
• district – Nombre del barrio;
• zipcode – Código postal;
• label – Dirección completa. Se recomienda armar el texto en el orden «Nombre de la calle, número, código postal, barrio, ciudad, estado».

Nota: Hay un límite de 200 puntos por enviar una misma solicitud.

Parâmetros opcionais

• mainLocation – Objeto con dos parámetros para limitar el área de búsqueda de direcciones:
  • center – Objeto con coordenadas de referencia para resultados de búsqueda. Las coordenadas se pueden ingresar en los siguientes formatos:
    • Objeto con las propiedades lat y lon que representan latitud y longitud respectivamente. Ejemplo: {"lat":-23.0852, "lon": -46.98020}
    • Array con latitud y longitud. Ejemplo: [-23.0852,  -46.98020]
    • Coordenadas codificadas como geohash. Ejemplo: "6tr6df675"
  • radius – Radio de búsqueda, en metros, desde el punto central definido en center. Si no se informa, el valor por defecto es 500.000 metros (500 km).
• limit – Limita el número de resultados devueltos. Es un query param, informado en la propia URL. Por ejemplo: https://api.maplink.global/geocode/v2/geocode?limit=1

Ejemplo 1 – Buscar coordenadas desde la dirección

En el siguiente ejemplo, solicitaremos las coordenadas de la dirección «Alameda Campinas, 579, São Paulo – SP, CEP 01404-100». La solicitud completa está a continuación:

{
    "road": "Alameda Campinas",
    "number": 579,
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01404000"
}

La consulta también podría realizarse utilizando el parámetro label, como se muestra en el siguiente ejemplo:

{
    "label": "Alameda Campinas, 579, 01404000, São Paulo,SP ",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01404000"
}

En ambos casos, se devuelve la siguiente información en la respuesta:

• found – Número de registros devueltos;
• results – Array de objetos con todos los resultados encontrados:
  • id – Identificador de la dirección proporcionada en la solicitud;
  • address – Objeto con información de dirección:
    • road – Nombre de la carretera;
    • district – Bairro;
    • zipCode – Código postal;
    • city – Ciudad;
    • state – Estado;
    • mainLocation – Objeto con las coordenadas geográficas del punto:
      • lat – Latitud;
      • lon – Longitud;
    • numberAsInteger – Número de dirección, pero devuelto como un número entero en lugar de una string;
  • type – Indica el mejor elemento encontrado en la base de datos cartográfica para devolver la coordenada geográfica;
  • score – Puntuación de referencia del resultado del proceso de geocodificación;
  • label – Dirección completa encontrada utilizada en el proceso de geocodificación.

La respuesta completa está a continuación:

{
    "found": 1,
    "results": [
        {
            "id": "6684353bf0662a1541ff635d",
            "address": {
                "road": "ALAMEDA CAMPINAS",
                "number": "579",
                "district": "JARDIM PAULISTA",
                "zipCode": "01404000",
                "city": "SÃO PAULO",
                "state": {
                    "name": "SÃO PAULO",
                    "code": "SP"
                },
                "mainLocation": {
                    "lat": -23.566329468025202,
                    "lon": -46.653621381930805
                },
                "numberAsInteger": 579
            },
            "type": "ROAD",
            "label": "ALAMEDA CAMPINAS, 01404000, JARDIM PAULISTA, SÃO PAULO, SP",
            "score": 100.0
        }
    ]

Nota: Cuanto mayor sea la score, mayor será la relevancia del resultado para la dirección solicitada. Por ejemplo, si la solicitud tiene todos los elementos de la dirección completados y fueron encontrados en la base de datos cartográfica, se espera una puntuación más alta. Si la solicitud solo tiene un código postal, por ejemplo, la puntuación será menor.

Ejemplo 2 – Búsqueda coordinada basada en código postal

En este ejemplo realizaremos una solicitud informando únicamente el código postal de Brasil 01014-000:

{
    "zipcode": "01014000"
}

La respuesta completa está a continuación:

 {
    "found": 1,
    "results": [
        {
            "id": "66843498f0662a1541f9c308",
            "address": {
                "road": "RUA BOA VISTA",
                "district": "CENTRO",
                "zipCode": "01014000",
                "city": "SÃO PAULO",
                "state": {
                    "name": "SÃO PAULO",
                    "code": "SP"
                },
                "mainLocation": {
                    "lat": -23.54685803583,
                    "lon": -46.63338712495
                }
            },
            "type": "ROAD",
            "label": "RUA BOA VISTA, 01014000, CENTRO, SÃO PAULO, SP",
            "score": 100.0
        }
    ]
}