Lupap Developers
Última actualización: 2022-08-28

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.

Para Colombia este valor debe ser co
city (Obligatorio) Representa la ciudad del país de la dirección a buscar.

  • Para ver los códigos de ciudades favor selecciona un país :
    • En el caso de Colombia, en este campo se puede hacer uso del código dane de 5 u 8 dígitos
    a (Obligatorio) a o address Representa la dirección a buscar.
    Importante: La dirección debe ser codificada.
    por ejemplo el símbolo # debe ser cambiado por %23 o el símbolo espacio debe ser cambiado por %20

    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 placa domiciliaria, casa, edificio o construcción. line_interpolation indica que el punto es una aproximación que se calcula a nivel de la calle o del frente de manzana.place Indica que se encontró un lugar o punto de interés y no una dirección. parcel_centroid indica que el punto es ubicado a en el centro del lote o predio. partial_match Indica que el resultado de la búsqueda corresponde a una coincidencia parcial del texto ingresado, para este caso se recomienda verificar la ortografía, buscar una dirección y no un lugar, todo esto con el fin de mejorar la exactitud del resultado obtenido. approximate Indica que el resultado es aproximación de la busqueda.
    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, Medellín, Envigado, 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

    Términos y Condiciones de uso  |  2015 -2022© Lupap  - Made with ♥ in Colombia.