Suggest

Servicios web

Documentación sobre la funcionalidad Suggest disponible a través del webservice HTTP-JSON de la plataforma CERCALIA.

La URL base a utilizar es:

* Clave de seguridad. Es la misma KEY que para la API de mapas de Cercalia

Las peticiones HTTP se pueden enviar en GET o POST
Las respuestas son en formato JSON

Introducción API Cercalia Suggest

Webservice suggest direcciones. Este servicio permite lanzar:

  1. Peticiones de sugerencias:
    Incluye direcciones, localidades y puntos de interés
  2. Peticiones para geocodificar direcciones
    Obtener la X,Y de una dirección

Las peticiones de sugerencias ya incluyen la coordenada de cada candidato, a excepción de las direcciones (sólo se devuelve la coordenada por defecto de la calle). En este caso es necesario realizar una segunda petición al webservice, para obtener las coordenadas de detalle del portal.

Dirección del WebService:
http://lb.cercalia.com/suggest/SuggestServlet?

Peticiones sugerencias

Petición:

Se acepta el método GET y POST.
Los parámetros siempre deben ir codificados en UTF-8

Parámetros de petición:

"key"
Clave de seguridad:

  • Para aplicaciones WEB, utilizar la misma KEY que para la API de mapas de Cercalia
  • Para el resto de aplicaciones (servidor, APP, ...), pedir una KEY a Nexus

"t"
Texto a buscar. Puede contener la calle, número, localidad, código postal, etc. El código postal actúa como limitador: en caso de no encontrar coincidencias amplía la búsqueda a todo el municipio perteneciente al CP.

"stnum"
Número de portal a buscar. No se extraerá de "t". Si "stnum" está informado, los valores numéricos de dentro de "t" se interpretarán como parte del nombre de la calle / población, no como número de portal.

"alllike"
Para utilizar like en todas las palabras. Utilizar los valores "Yes","Y" o "1".

"nofuzzy"
Para no utilizar fuzzy (búsqueda de palabras similares). Utilizar los valores "Yes","Y" o "1".

"getype"
Filtro por tipos de elemento. Lista separada por comas.
Posibles valores:

  • st= Calles
  • ct= Localidades
  • all= los devuelve todos, equivale a no enviar el parámetro

Ej.: getype=st,ct

Filtros opcionales:

  • ctryc: código de país (ej: ESP,FRA)
  • regc: código de región - comunidad (ej: ESPMAD,ESPCAT)
  • subregc: código de subregión - provincia (ej:ESP08,EPS28)
  • munc: código de municipio (ej: ESP080193,ESP280796)
  • rsc: código de municipio / región / subregión / país (substituye munc, subregc , regc y ctryc). Ej: ESP,ESPMAD,ESP08,ESP410917
  • rscp: código de municipio / región / subregión / país preferido. Este filtro, prioriza los resultados que se encuentren en las regiones especificadas, por encima del resto de candidatos, llenando la lista de sugerencias con los candidatos de la región /es priorizadas (siempre que encuentre candidatos), pero no elimina los resultados del resto de regiones o países. Este filtro se puede combinar con el filtro "rsc", para obtener un filtro máximo de resultados más allá de los preferidos. Ej: ESPVAL
    * rscp1 – rscp2 ...: En caso de necesitar priorizar los candidatos dentro de la lista de regiones preferidas, pueden separarse las regiones por parámetros separados según nivel de prioridad: rscp1: prioridad máxima, rscp2: segundo nivel de prioridad, ...
  • rsclp: código de municipio / región / subregión / país preferido. No compatible con el filtro rscp Este filtro, prioriza de manera más suave que "rscp" los resultados que se encuentren en las regiones especificadas: solo recoge un máximo de 3 candidatos de mayor score de las regiones especificadas, y no elimina los del resto de regiones. Este filtro se puede combinar con el filtro "rsc", para obtener un filtro máximo de resultados más allá de los preferidos. Ej: ESPVAL
    * rsclp1 – rsclp2 ...: En caso de necesitar priorizar los candidatos dentro de la lista de regiones preferidas, pueden separarse las regiones por parámetros separados según nivel de prioridad: rsclp1: prioridad máxima, rsclp2: segundo nivel de prioridad, ...
  • stc: código de calle (ej: ESP280796000099043)
  • hnrt: aplicar una tolerancia en el número de portal buscado, para priorizar direcciones que contengan el número de portal buscado, incluyendo el margen de tolerancia. Este margen es de 50 números, y 500 en el caso de USA (el de USA aplica siempre que se filtre la búsqueda a nivel de USA o una de sus regiones). Posible valores:
    [0] = no aplica. Valor por defecto
    [1] = aplica

Filtro por radio:

Permite filtrar los resultados por proximidad a un punto (coordenada). Se trata de un filtro restrictivo (solo devuelve candidatos que se encuentren dentro del radio).

  • pt: coordenada "lat,lon"
  • d: distancia radial en kilómetros, por defecto 25 km. El valor mínimo también es de 25 km

Ej: pt=40.417025,-3.703505&d=25

Ejemplo de petición:
http://lb.cercalia.com/suggest/SuggestServlet?key=xxxxxxxxxxxx&t=avinguda%20diagonal%20200,%20barcelona&getype=st,ct&ctryc=ESP

Respuesta:

La respuesta siempre se devuelve en formato JSON.
La respuesta siempre se devuelve con codificación UTF-8.

Tipos de elementos devueltos por la API de sugerencias:

Localidad

Si el campo "id" empieza por 'CT', es una localidad.

Direcciones

Si el campo "id" empieza por 'ST', es una calle.

La calle también puede tener los campos opcionales "portal_min" , "portal_max" , "portal" , "portal_disponible" y/o "portal_en".

  • "portal" (número del portal) aparece cuando se ha separado el número del resto de la dirección.
  • "portal_disponible" (número del portal disponible) aparece cuando se ha separado el número del resto de la dirección y se ajusta a los portales disponibles para cada dirección.
  • "portal_en" indica si la dirección el usuario la ha escrito en formato inglés [true/false].
  • "codigo_postal" indica el código postal de la dirección, siempre y cuando esté disponible y/o se haya indicado una dirección completa (calle y número).

Ejemplo de respuesta:

{
   responseHeader:{
      status:0,
      QTime:88,
      params:{
         ctryc:"ESP",
         getype:"st,ct",
         key:"07de1b67aa00baf5f1284298f88132e3914e4fb380fce9d91c815aa372fe67c4",
         t:"paseo de la castellana 300, madrid"
      }
   },
   response:{
      numFound:1,
      start:0,
      maxScore:2134.202,
      docs:[
         {
            id:"STESP215604",
            calle_id:"ESP280796000091443",
            calle_descripcion:"Paseo de la Castellana",
            calle_nombre:"Castellana",
            calle_tipo:"Paseo",
            calle_articulo:"de la",
            localidad_id:"ESP17240001236707",
            localidad_nombre:"Madrid",
            municipio_id:"ESP280796",
            municipio_nombre:"Madrid",
            provincia_id:"ESP28",
            provincia_nombre:"Madrid",
            comunidad_id:"ESPMAD",
            comunidad_nombre:"Comunidad de Madrid",
            pais_id:"ESP",
            pais_nombre:"España",
            oficial:"Y",
            portal_min:1,
            portal_max:308,
            puntuacio:2,
            coord:"40.482803,-3.682507",
            _version_:1645646022384287700,
            portal:300,
            portal_disponible:300,
            portal_en:false,
            score:2134.202,
            codigo_postal:"28046"
         }
      ]
   }
}

 

Cruces de calle & dirección con referencia a segunda calle

La respuesta es igual a la de direcciones con la información de la segunda calle del cruce, más un elemento "intersection" en cada candidato, donde el elemento "intersection" contiene la información de la primera calle del cruce, pero con la coordenada "coord" del cruce.

Permite buscar / geocodificar dos tipos de direcciones:

  • Cruces de calle: Ejemplo: Calle de Diego de León / Velázquez, Madrid (España)
  • Dirección exacta de una calle, referenciando a una calle con la que cruza (sistema comúnmente utilizado en países como Turquía o Colombia). Ejemplos:
    • Namik Kemal Sokak & Kocayol Caddesi 12, Bostanci (Turquía)
    • Carrera 69P & calle 70-63, Bogotá (Colombia)

Para separar la primera calle de la segunda se puede utilizar el separador " & " o " / ", con los espacios. Si no hay espacios entre el separador se entenderá que forma parte del propio nombre de calle.

Ejemplo respuesta:
"avinguda diagonal & rambla catalunya, barcelona""

{
   responseHeader:{
      status:0,
      QTime:972,
      params:{
         ctryc:"ESP",
         getype:"st,ct",
         key:"07de1b67aa00baf5f1284298f88132e3914e4fb380fce9d91c815aa372fe67c4",
         t:"avinguda diagonal / rambla catalunya, barcelona"
      }
   },
   response:{
      numFound:2,
      start:0,
      maxScore:112.967384,
      docs:[
         {
            id:"STESP51095",
            calle_id:"ESP080193000000807",
            calle_descripcion:"Avinguda Diagonal / Rambla de Catalunya",
            calle_nombre:"Catalunya",
            calle_tipo:"Rambla",
            calle_articulo:"de",
            localidad_id:"ESP17240008430951",
            localidad_nombre:"Barcelona",
            municipio_id:"ESP080193",
            municipio_nombre:"Barcelona",
            provincia_id:"ESP08",
            provincia_nombre:"Barcelona",
            comunidad_id:"ESPCAT",
            comunidad_nombre:"Catalunya",
            pais_id:"ESP",
            pais_nombre:"España",
            oficial:"Y",
            portal_min:1,
            portal_max:137,
            puntuacio:1.9,
            coord:"41.395714,2.1569343",
            _version_:1645646009292816400,
            score:129.48283,
            intersection:{
               id:"STESP853564",
               calle_id:"ESP080193000092155",
               calle_descripcion:"Avinguda Diagonal",
               calle_nombre:"Diagonal",
               calle_tipo:"Avinguda",
               localidad_id:"ESP17240008430951",
               localidad_nombre:"Barcelona",
               municipio_id:"ESP080193",
               municipio_nombre:"Barcelona",
               provincia_id:"ESP08",
               provincia_nombre:"Barcelona",
               comunidad_id:"ESPCAT",
               comunidad_nombre:"Catalunya",
               pais_id:"ESP",
               pais_nombre:"España",
               oficial:"Y",
               portal_min:1,
               portal_max:9998,
               puntuacio:1.9,
               coord:"41.395706,2.1569269",
               _version_:1645646071517413400,
               score:112.967384
            }
         },
         {
            id:"STESP607177",
            calle_id:"ESP080193000002900",
            calle_descripcion:"Avinguda Diagonal / Rambla del Poblenou",
            calle_nombre:"Poblenou",
            calle_tipo:"Rambla",
            calle_articulo:"del",
            localidad_id:"ESP17240008430951",
            localidad_nombre:"Barcelona",
            municipio_id:"ESP080193",
            municipio_nombre:"Barcelona",
            provincia_id:"ESP08",
            provincia_nombre:"Barcelona",
            comunidad_id:"ESPCAT",
            comunidad_nombre:"Catalunya",
            pais_id:"ESP",
            pais_nombre:"España",
            oficial:"Y",
            portal_min:1,
            portal_max:227,
            puntuacio:1.9,
            coord:"41.405388,2.1957703",
            _version_:1645646052257169400,
            score:80.742424,
            intersection:{
               id:"STESP853564",
               calle_id:"ESP080193000092155",
               calle_descripcion:"Avinguda Diagonal",
               calle_nombre:"Diagonal",
               calle_tipo:"Avinguda",
               localidad_id:"ESP17240008430951",
               localidad_nombre:"Barcelona",
               municipio_id:"ESP080193",
               municipio_nombre:"Barcelona",
               provincia_id:"ESP08",
               provincia_nombre:"Barcelona",
               comunidad_id:"ESPCAT",
               comunidad_nombre:"Catalunya",
               pais_id:"ESP",
               pais_nombre:"España",
               oficial:"Y",
               portal_min:1,
               portal_max:9998,
               puntuacio:1.9,
               coord:"41.405384,2.19577",
               _version_:1645646071517413400,
               score:112.967384
            }
         }
      ]
   }
}

Peticiones geocodificación direcciones

Petición:

Para geocodificar una dirección (obtener las coordenadas exactas de detalle del portal), es necesario recoger los parámetros de respuesta de sugerencias del candidato seleccionado, y lanzar la petición con estos parámetros:

"key"
Clave de seguridad:

  • Para aplicaciones WEB, utilizar la misma KEY que para la API de mapas de Cercalia
  • Para el resto de aplicaciones (servidor, APP, ...), pedir una KEY a Nexus

"ctc"
Código de localidad (campo localidad_id del suggest)

"stc"
Código de calle (campo calle_id del suggest)

"stnum"
Número de portal (campo portal)

Es obligatorio informar de todos los códigos obtenidos en la respuesta. Es posible que para algunos países no se devuelva el Código Postal.

Ejemplo petición:
http://lb.cercalia.com/suggest/SuggestServlet?key=xxxxxxxxx&ctc=ESP17240207272367&stc=ESP030149000090298&stnum=17

Respuesta:

La respuesta siempre se devuelve en formato JSON.
La respuesta siempre se devuelve con codificación UTF-8.

La respuesta incluye las coordenadas, en formato geográficas. Ejemplo de respuesta

{
   error:{
      code:6,
      msg:"Candidatos incorrectos"
   },
   responseHeader:{
      QTime:0,
      params:{
         ctc:"ESP17240207272367",
         key:"07de1b67aa00baf5f1284298f88132e3914e4fb380fce9d91c815aa372fe67c4",
         stc:"ESP030149000090298",
         stnum:"17"
      },
      status:6
   }
}

Cruces de calle

Ejemplo: Calle de Diego de León / Velázquez, Madrid (España)

Para este caso, NO es necesario realizar la petición de geocodificación de direcciones (aunque se puede hacer), puesto que la respuesta del servicio de sugerencias ya incorpora la coordenada del cruce de calles.

Peticiones sugerencias Puntos de Interés (POI)

Petición:

Se acepta el método GET y POST.
Los parámetros siempre deben ir codificados en UTF-8.

"key"
Clave de seguridad:

  • Para aplicaciones WEB, utilizar la misma KEY que para la API de mapas de Cercalia
  • Para el resto de aplicaciones (servidor, APP, ...), pedir una KEY a Nexus

"pois"
Enviar siempre "pois" con valor a "1".

"t"
Texto a buscar. Puede contener la calle, número, localidad, código postal, etc. El código postal actúa como limitador: en caso de no encontrar coincidencias amplía la búsqueda a todo el municipio perteneciente al CP.

"nofuzzy"
Para no utilizar fuzzy (búsqueda de palabras similares). Utilizar los valores "Yes","Y" o "1".

Filtros opcionales:

  • ctryc: código de país (ej: ESP,FRA)
  • regc: código de región - comunidad (ej: ESPMAD,ESPCAT)
  • subregc: código de subregión - provincia (ej:ESP08,EPS28)
  • munc: código de municipio (ej: ESP080193,ESP280796)
  • rsc: código de municipio / región / subregión / país (substituye munc, subregc , regc y ctryc). Ej: ESP,ESPMAD,ESP08,ESP410917
  • rscp: código de municipio / región / subregión / país preferido. Este filtro, prioriza los resultados que se encuentren en las regiones especificadas, por encima del resto de candidatos, llenando la lista de sugerencias con los candidatos de la región /es priorizadas (siempre que encuentre candidatos), pero no elimina los resultados del resto de regiones o países. Este filtro se puede combinar con el filtro "rsc", para obtener un filtro máximo de resultados más allá de los preferidos. Ej: ESPVAL
    * rscp1 – rscp2 ...: En caso de necesitar priorizar los candidatos dentro de la lista de regiones preferidas, pueden separarse las regiones por parámetros separados según nivel de prioridad: rscp1: prioridad máxima, rscp2: segundo nivel de prioridad, ...
  • rsclp: código de municipio / región / subregión / país preferido. No compatible con el filtro rscp Este filtro, prioriza de manera más suave que "rscp" los resultados que se encuentren en las regiones especificadas: solo recoge un máximo de 3 candidatos de mayor score de las regiones especificadas, y no elimina los del resto de regiones. Este filtro se puede combinar con el filtro "rsc", para obtener un filtro máximo de resultados más allá de los preferidos. Ej: ESPVAL
    * rsclp1 – rsclp2 ...: En caso de necesitar priorizar los candidatos dentro de la lista de regiones preferidas, pueden separarse las regiones por parámetros separados según nivel de prioridad: rsclp1: prioridad máxima, rsclp2: segundo nivel de prioridad, ...
  • id: código de poi (ej: PESP724009000642061)
  • id: código de categoría de POI. Lista separada por comas. Ej:
    ctryc=ESP
    poicat=C005,C043
    munc=ESP080193,ESP170792

Filtro por radio:

Permite filtrar los resultados por proximidad a un punto (coordenada). Se trata de un filtro restrictivo (solo devuelve candidatos que se encuentren dentro del radio).

  • pt: coordenada "lat,lon"
  • d: distancia radial en kilómetros, por defecto 25 km. El valor mínimo también es de 25 km

Ej: pt=40.417025,-3.703505&d=25

Ejemplo petición:
http://lb.cercalia.com/suggest/SuggestServlet?key=xxxxxxxxxxxx&pois=1&t=Museo%20del%20Prado%20Madrid&ctryc=ESP

Respuesta:

La respuesta siempre se devuelve en formato JSON.
La respuesta siempre se devuelve con codificación UTF-8.

Tipos de elementos devueltos por la API de sugerencias:

  • Si el campo "id" empieza por "P" es un punto de interés (POI).

Listado de categorías de POIs:

CÓDIGO DESCRIPCIÓN

C013

Hotel

C031

Teatro

C009

Hospital / servicios de salud

C036

Casino

C030

Museo

C045

Parque de atracciones

C048

Zoo

C006

Terminal de Ferry

C015

Estadio / centro deportivo

C004

Estación de ferrocarril

C005

Aeropuerto

7389

Terminal Aeropuerto

C043

Centro de convenciones

C010

Centro comercial

C037

Atracción turística importante

9942

Parada de transporte público

LU01

Parque urbano

9383

Planta industrial / Empresa

7377

Universidad

7367

Administración pública

D00ESC

Escuela

7319

Centro cultural

7347

Puerto/Marina

7360

Camping

9911

Golf

7376

Centro de culto

Ejemplo de respuesta:

{
   responseHeader:{
      status:0,
      QTime:23,
      params:{
         ctryc:"ESP",
         key:"07de1b67aa00baf5f1284298f88132e3914e4fb380fce9d91c815aa372fe67c4",
         pois:"1",
         t:"Museo del Prado Madrid"
      }
   },
   response:{
      numFound:3,
      start:0,
      maxScore:26.154898,
      docs:[
         {
            id:"PESP724009001959912",
            categoria_id:"C037",
            poi_nombre:"Museo Nacional del Prado",
            codigo_postal:"28014",
            localidad_nombre:"Madrid",
            municipio_id:"ESP280796",
            municipio_nombre:"Madrid",
            provincia_id:"ESP28",
            provincia_nombre:"Madrid",
            comunidad_id:"ESPMAD",
            comunidad_nombre:"Comunidad de Madrid",
            pais_id:"ESP",
            pais_nombre:"España",
            direccion:"Paseo del Prado, 28014 Madrid",
            calle_descripcion:"Paseo del Prado",
            puntuacio:1,
            coord:"40.414856,-3.6925297",
            lang:"SPA",
            _version_:1645647790034911200,
            score:26.154898
         },
         {
            id:"PESP724009000642061",
            categoria_id:"C030",
            poi_nombre:"Museo del Prado",
            codigo_postal:"28014",
            localidad_nombre:"Madrid",
            municipio_id:"ESP280796",
            municipio_nombre:"Madrid",
            provincia_id:"ESP28",
            provincia_nombre:"Madrid",
            comunidad_id:"ESPMAD",
            comunidad_nombre:"Comunidad de Madrid",
            pais_id:"ESP",
            pais_nombre:"España",
            direccion:"Paseo del Prado, 28014 Madrid",
            calle_descripcion:"Paseo del Prado",
            tel:"+(34)-(913)-302800",
            mail:"museo.nacional@museodelprado.es",
            web:"www.museoprado.mcu.es",
            puntuacio:0.9,
            coord:"40.413776,-3.6924677",
            lang:"SPA",
            _version_:1645647790035959800,
            score:23.539408
         },
         {
            id:"PESPLU01N2945",
            categoria_id:"LU01",
            poi_nombre:"Jardines del Museo del Prado",
            localidad_nombre:"Madrid",
            municipio_id:"ESP280796",
            municipio_nombre:"Madrid",
            provincia_id:"ESP28",
            provincia_nombre:"Madrid",
            comunidad_id:"ESPMAD",
            comunidad_nombre:"Comunidad de Madrid",
            pais_id:"ESP",
            pais_nombre:"España",
            puntuacio:0.8,
            coord:"40.414196,-3.6926923",
            _version_:1645647795570344000,
            score:20.923918
         }
      ]
   }
}

Error

Si "status" es 0, la respuesta es correcta.

Respuesta de error: cuando "status" diferente a 0.

{
   "responseHeader":{
      "QTime":0,
      "params":{
         "key":"______",
         "ctryc":"esp",
         "ctc":"ESP17240205556728",
         "stc":"ESP170792000090959",
         "stnum":"17"
      },
      "status":1
   },
   "error":{
      "code":1,
      "msg":"FileNotFoundException: http://lb.cercalia.com/cercalia_lbs/server?cmd=cand&detcand=1&clientid=___&ctc=ESP17240205556728&ctryc=esp&stc=ESP170792000090959&stnum=17"
   }
}

Peticiones sugerencias de direcciones con la localidad entre corchetes cuadrados.

Petición:

Parámetros de la petición:

"t" = Texto a buscar. Puede contener la dirección (calle, número, código postal). Y en este caso el nombre de localidad esta entre corchetes cuadrados al final del texto. Se ignorará la parte que vaya después de la localidad.

Es importante tener en cuenta que utilizando este sistema de búsqueda se tiene que incluir solo la dirección y la población, puesto que busca concordancias solo en los campos de calle y localidad.

Ejemplo:

  • Calle de Alcalá 550 [Madrid]
  • Calle de Alcalá 550, 28022 [Madrid]

El resto de parámetros son iguales a las peticiones anteriores de sugerencias.

Respuesta:

Igual al resto de las peticiones anteriores de sugerencias.