Autenticación

Para utilizar nuestros servicios de geocodificación solo debes registrarte, obtener un api key y un api secret y hacer los siguientes llamados a nuestra API vía http(s).

Recuerda que todos los llamados deben hacer uso de la autenticación básica por http.

Hemos agregado la opción de crear un web token para llamados que se hagan directamente desde un navegador vía javascript. Este token lo puedes generar desde tu dashboard en tu cuenta.


Gecodificación (Versión 2)

Créditos

Cada dirección encontrada equivale a un (1) crédito. Para el caso de la gecodificación reversa todas las peticiones equivalen a un (1) crédito.

Gecodificación de direcciones

GET http(s)://api.lupap.co/v2/{country}/{city}?a={address}[&key={WEB_TOKEN}]

Parámetro Descripción
country (Obligatorio) Código de dos letras que representa el país de la dirección a buscar.

city (Obligatorio) Representa la ciudad del país de la dirección a buscar.

  • selecciona un país
address (Obligatorio) Representa la dirección a buscar.
Importante: La dirección debe ser codificada.

key (Opcional) Representa un token de acceso para applicaciones (preferiblemente) web. Por ejemplo para hacer llamados desde javascript (jquery, angular, etc) directamente a nuestro API se puede incluir este parámetro. Los web tokens estan asociados a un API KEY y API SECRET y se pueden crear en el dashboard de administración de tu cuenta.

Gecodificación Reversa

GET http(s)://api.lupap.co/v2/reverse?lon={lon}&lat={lat}[&key={WEB_TOKEN}]

Parámetro Descripción
lon (Obligatorio) Representa la longitud del punto (coordenada) a buscar.
lat (Obligatorio) Representa la latitud del punto (coordenada) a buscar.
key (Opcional) Representa un token de acceso para applicaciones (preferiblemente) web. Por ejemplo para hacer llamados desde javascript (jquery, angular, etc) directamente a nuestro API se puede incluir este parámetro. Los web tokens estan asociados a un API KEY y API SECRET y se pueden crear en el dashboard de administración de tu cuenta.

Consultar Lugar por Identificador

GET http(s)://api.lupap.co/v2/place/{id}[?key={WEB_TOKEN}]

Parámetro Descripción
(Obligatorio)Identificador del Lugar Representa el identificador del lugar, este puede ser obtenido del autocompletador de direcciones y lugares

Respuesta

La respuesta tiene un formato GeoJSON y pueden ser de dos tipos: Las respuestas de un solo resultado seran representadas por un objeto GeoJSON de tipo Feature. Las respuestas de multiples resultados seran representadas por un objeto GeoJSON de tipo FeatureCollection. Cada Feature se define de la siguiente forma:

// respuesta simple:
{
    "response": {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                -74.04659813699993,
                4.720145423000076
            ]
        },
        "properties": {
            "accuracy": "rooftop",
            "country": "co",
            "city": "bogota",
            "attribution": "geoapps",
            "commonName": "AVENIDA SANTA BARBARA",
            "address": "AK 19 # 135 - 30",
            "postcode": "110121",
            "admin1": "Colombia",
            "admin2": "Bogotá D.C.",
            "admin3": "Bogotá D.C.",
            "admin4": "Usaquen",
            "admin5": "El Contador"
        }
    } 
}

// respuesta múltiple:
{
   "response" : {
      "type" : "FeatureCollection",
      "features" : [ // arreglo de objetos de tipo Feature
          {
              "type" : "Feature",
              "geometry" : {
                  "type" : "Point",
                  "coordinates": [
                      -74.04659813699993,
                      4.720145423000076
                  ]
              },
              "properties" : {
                 "accuracy": "rooftop",
                 "country": "co",
                 "city": "bogota",
                 "attribution": "geoapps",
                 "commonName": "AVENIDA SANTA BARBARA",
                 "address": "AK 19 # 135 - 30",
                 "postcode": "110121",
                 "admin1": "Colombia",
                 "admin2": "Bogotá D.C.",
                 "admin3": "Bogotá D.C.",
                 "admin4": "Usaquen",
                 "admin5": "El Contador"
             }
          }
	 
      ... // mas objetos de tipo Feature

      ]
   }
}
		
Atributo Descripción
geometry.type Point define el tipo de geometría, para nuestro caso siempre será un punto
geometry.coordinates Una arreglo de dos posiciones con la longitud y la latitud de la dirección [longitud, latitud]
properties.accuracy Representa la exactitud de la ubicación de la dirección. rooftop indica que el punto es ubicado a nivel de la casa, edificio o lote. line_interpolation indica que el punto es una aproximación a nivel de la calle o del frente de manzana
properties.country Representa el código del país
properties.city Representa el código de la ciudad
properties.attribution Representa el tipo de atribución de los datos, puede ser lupap|geoapps|osm
properties.commonName Representa el nombre de la dirección, por ejemplo AVENIDA BOYACA para la AK 72 en Bogotá, Colombia
properties.address Representa la dirección estandarizada.
ste valor puede ser null cuando se consulta un lugar, como por ejemplo un barrio, que no tiene asociada ninguna dirección
properties.postcode Representa el código postal, este valor puede ser null
properties.admin1 Representa el nombre del país
properties.admin2 Representa el nombre del departamento
properties.admin3 Representa el nombre del municipio o ciudad
properties.admin4 Representa el nombre de la comuna o localidad. este valor puede ser null
properties.admin5 Representa el nombre del barrio. este valor puede ser null

Autocompletado de direcciones
y lugares

Créditos

Cada petición realizada equivale a 0.1 créditos. Cuando el resultado es vacio no se consumiran créditos.

End Point

GET
http(s)://api.lupap.co/v2/suggestions?q={query}&searchType=address&city={city}[&key={WEB_TOKEN}]

Parámetro Descripción
q (obligatorio) Representa el parámetro de búsqueda, es decir la palabra o termino a buscar.
En el caso de las direcciones, la búsqueda este parámetro representa el prefijo a buscar.
En el caso de lugares, este parámetro será buscado dentro del nombre del lugar sin importar su posición.
searchType (obligatorio) Representa el tipo de elementos a buscar y puede tomar los siguientes valores:

addresses Indica que solamente se van a sugerir direcciones

places Indica que solamente se van a sugerir lugares

all Indica que se los resultados serán tanto direcciones como lugares

city (opcional) Representa el código de la ciudad donde se va a realizar la búsqueda. El código de la ciudad es el mismo utilizado en la geocodificación de direcciones. Este parámetro tambien puede tomar el valor all

  • all retorna todas las direcciones y lugares que coinciden con q en todas las ciudades disponibles
Nota: Inicialmente el servicio de autocompletado de direcciones se ofrece para las ciudades de Bogotá, Soacha, Villavicencio en Colombia y el autocompletado de lugares para Cali y Bogotá. Constantemente estaremos agregando direcciones y lugares de otras ciudades y municipios de Colombia.
key (Opcional) Representa un token de acceso para applicaciones (preferiblemente) web. Por ejemplo para hacer llamados desde javascript (jquery, angular, etc) directamente a nuestro API se puede incluir este parámetro. Los web tokens estan asociados a un API KEY y API SECRET y se pueden crear en el dashboard de administración de tu cuenta.

Respuesta

Importante: Ningún objeto retorna las coordenadas, para esto se debe hacer un llamado al end point de geocodificación en el caso que los objetos retornados sean direcciones, es decir si type == "address", de la siguiente forma:

http(s)://api.lupap.co/v2/{countryCode}/{cityCode}?a={name}

reemplazando los valores countryCode, cityCode y name con los valores retornados en la respuesta, ver descripción más adelante

Cuando el resultado es un lugar, es decir cuando type == "place", se debe consultar el lugar por su identificador llamando al end point de consulta de lugares por identificador de la siguiente forma:

http(s)://api.lupap.co/v2/place/{id}

reemplazando el valor de id con el identificador del lugar, ver descripción más adelante

Para las direcciones se retorna un arreglo de objetos json con el siguiente esquema:

[
// para direcciones:
  {
    "city": "Bogotá D.C.",
    "cityCode": "bogota",
    "countryCode": "co",
    "name": "Avenida Carrera 0 # 83A - 0",
    "id": "4f7cbbc08ae84511e59bde440e7c174d8725f755",
    "type": "address"
  },
  {
    "city": "Bogotá D.C.",
    "cityCode": "bogota",
    "countryCode": "co",
    "name": "Avenida Carrera 1 # 22 - 80",
    "id": "4c0525d4d8d1eb0639e225eaf53ff173532eb24c",
    "type": "address"
  },
  ...
  // para lugares:
  {
    "country": "Colombia",
    "address": "CLUB CAMPESTR E LOS ARRAYANES LA LOMITA",
    "city": "Bogotá D.C.",
    "countrycode": "co",
    "type": "place",
    "categoryType": [
      "all",
      "na"
    ],
    "geomId": "07c90288-20b1-4f10-a779-e1d8f21283ea",
    "citycode": "bogota",
    "name": "Club Los Arrayanes",
    "bounds": [
      -74.0734471309999,
      4.78985645300008,
      -74.0734471309999,
      4.78985645300008
    ],
    "state": "Bogotá D.C",
    "id": "07c90288-20b1-4f10-a779-e1d8f21283ea",
    "value": "Club Los Arrayanes"
  },
  {
    "country": "Colombia",
    "address": "CL 60 SUR NO. 80K-02",
    "city": "Bogotá D.C.",
    "countrycode": "co",
    "type": "place",
    "categoryType": [
      "all",
      "education"
    ],
    "geomId": "1b1ba250-c8e5-426f-8821-a77c49e2c1e5",
    "citycode": "bogota",
    "name": "Colegio Claretiano",
    "bounds": [
      -74.1838973279999,
      4.61176010900004,
      -74.1838973279999,
      4.61176010900004
    ],
    "state": "Bogotá D.C",
    "id": "1b1ba250-c8e5-426f-8821-a77c49e2c1e5",
    "value": "Colegio Claretiano"
  }
  ...
]

		
Atributo Descripción
city Nombre de la ciudad
cityCode Código de la ciudad para la geocodificación de la dirección
countryCode Código del país para la geocodificación de la dirección
name Nombre a mostrar, en el caso de ser tipo address este campo puede ser usado para geocodificar la dirección
id Identificador del objeto retornado
type address cuando representa una dirección
Para los lugares se retorna, dentro del arreglo, los objetos json con el siguiente esquema:

Atributo Descripción
type place cuando representa un lugar
id identificador del lugar
value Nombre del lugar
name Nombre del lugar
address Dirección del lugar, puede ser null
country Nombre del país
state Nombre del estado o departamento
city Nombre de la ciudad
categoryType Arreglo con los tipos de las diferentes categorías a las que pertenece el lugar
countrycode código ISO 3166 de dos caracteres del país
citycode código de la ciudad de acuerdo al estándar de lupap
geomId Identificador de la geometría que representa el lugar
bounds Coordenadas máximas y mínimas que definen el cuadrado mínimo que contiene a la geometría que representa el lugar

Estados de respuesta

Código Mensaje Descripción
200
La consulta fue satisfactoria y se retornaron los resultados
401
Need authentication Se requiere el tokenKey y el tokenSecret para autenticar la consulta
400
Verify the parameters Algunos de los paráametros obligatorios no fueron definidos
404
Application not found El tokenKey no corresponde a una aplicación valida
401
Not authorized application El tokenKey y/o el tokenSecret no son validos para hacer la consulta
400
Transactions out of date Las transacciones asignadas a un periodo de tiempo se han vencido.
400
Not available transactions No hay transacciones disponibles para hacer consultas
404
Result not found El resultado consultado no se ha encontrado
500
Hubo un error interno del sistema. En caso de presentarse por favor reportarlo a info@lupap.com

Licencia de datos

  • Para todos los datos aplican, y por tanto se deben leer y aceptar, los términos y condiciones de uso de nuestra API
  • Los datos de la Ciudad de Bogotá se rigen por la licencia de datos abiertos del IDECA
  • Los datos de la Ciudad de Medellín se rigen por la licencia de datos abiertos del municipio de Medellín
  • Para datos de OSM © OpenStreetMap