Suggest

Web Services

This document describes functionality of Suggest, available from HTTP-JSON webservice of the CERCALIA platform.

The base URL to use is:

* Security key. It is the same KEY as for the Cercalia Maps API

HTTP requests can be sent via GET or POST
The service returns responses with JSON format

Cercalia Suggest API

This service allows to launch:

  1. Suggests requests:
    It includes addresses, locations and points of interest.
    Does not include the coordinates of the address,, if you want this coordinates you must do an request to the geocoding address service
  2. Geocoding address service
    Get the X, Y coordinates of an address

Requests for suggestions already include each candidate's coordinate , with the exception of the addresses ( only the default street coordinate is returned ). In this case it is necessary to make a second request to the webservice, to obtain the detailed coordinates of the portal.

Suggest's reponses already include each candidate's coordinates, with the exception of portal candidates (where only the default street coordinate is returned). In this case it is necessary to make a second request to the webservice, to obtain the detailed coordinates of the portal.

Web Service URL:
http://ws.cercalia.com/suggest/SuggestServlet?

Suggests requests

Request:

The GET and POST methods are accepted.
The parameters must always be encoded in UTF-8

Request Parameters:

"key"
Security key:

  • For Web applications, use the same KEY as for the Cercalia Maps API
  • For all other types of applications (server, APP, ...), you must request a KEY to Nexus

"t"
Text to search. It can contain the street, number, location, zip code, etc. The postal code acts as a limiter: in case of not finding matches, it broadens the search to the entire municipality belonging to the CP.


Optional Parameters:

"stnum"
Portal number to search. It will not be extracted from "t". . If "Si "stnum" is informed, the numerical values ​​within "t" will be interpreted as part of the street / town name, not as a portal number.

"alllike"
Use "like" comparator in all the words. Use the values ​​"Yes", "Y" or "1".

"nofuzzy"
Don't use fuzzy search (search of similar words). Use the values ​​"Yes", "Y" or "1".

"getype"
type of element filter. Comma separated list.
Possible values:

  • st= Streets
  • ct= Localities
  • all= returns all of them, equivalent to not sending the parameter

Ex.: getype=st,ct
 

Optional filters:

  • ctryc: country code(Ex: ESP,FRA)
  • regc: region code - autonomous community (Ex: ESPMAD,ESPCAT)
  • subregc: subregion code - province (Ex:ESP08,EPS28)
  • munc: municipality code (Ex: ESP080193,ESP280796)
  • rsc: municipality / region / subregion / country code (replaces munc, subregc, regc and ctryc). Ex: ESP,ESPMAD,ESP08,ESP410917
  • rscp: municipality / region / subregion / country code prioritized. This filter, prioritizes the results in the specified regions, over the rest of the candidates, filling out the list of suggestions with the candidates in the prioritized region (whenever you find candidates), but does not delete the results from the rest regions or countries. This filter can be combined with the "rsc" filter to get a maximum filter of results beyond favorites. Ex: ESPVAL
    * rscp1 – rscp2 ...: If you need to prioritize the candidates in the list of preferred regions, the regions can be separated by separate parameters according to priority level: rscp1: maximum priority, rscp2: second priority level, ...
  • rsclp: municipality / region / subregion / country code prioritized. Not compatible with rscp filter. This filter prioritizes the results found in the specified regions more gently than "rscp": it only collects a maximum of 3 candidates with the highest scores from the specified regions, and does not eliminate those from the rest of the regions. This filter can be combined with the "rsc" filter, to obtain a maximum filter of results beyond the preferred ones. Ex: ESPVAL
    * rsclp1 – rsclp2 ...: Preferred municipality / region / subregion / country code. Not compatible with rscp filter. This filter, prioritizes smoother than "rscp" results in the specified regions: Only picks up to 3 top scoring candidates from the specified regions, and does not remove those from the rest of the regions. This filter can be combined with the "rsc" filter to get a maximum filter of results beyond favorites. Ex: ESPVAL * rscp1 - rscp2 ...: If you need to prioritize the candidates in the list of preferred regions, the regions can be separated by separate parameters according to priority rsclp1: maximum priority, rsclp2: second priority level, ...
  • stc: street code (ex: ESP280796000099043)
  • hnrt: Apply a tolerance on the searched portal number, to prioritize addresses that contain the searched portal number, including the tolerance range. This margin is 50 numbers, and 500 in the case of USA (USA applies whenever the search is filtered at the level of USA or one of its regions). Possible values:
    [0] = not applicable. Default value
    [1] = apply
  • lang: preferred language codes. Ex: lang=baq,spa -> priorices Basque, and Spanish if Basque is not available. Main languages:

Language

Code

Arabic

ARA

Basque

BAQ

Catalan

CAT

Czech

CZE

Croatian

SCR

Danish

DAN

Estonian

EST

Finnish

FIN

Dutch

DUT

English

ENG

French

FRE

Galician

GLG

German

GER

Greek

GRE

Hebrew

HEB

Hindi

HIN

Hungarian

HUN

Icelandic

ICE

Italian

ITA

Latvian

LAV

Lithuanian

LIT

Norwegian

NOR

Polish

POL

Portuguese

POR

Romanian

RUM

Russian

RUS

Slovak

SLO

Slovenian

SLV

Swedish

SWE

Turkish

TUR

Valencian

VAL


Proximity filter:

You can filter the results by proximity to a point (coordinate). It is a restrictive filter (only returns candidates that are within the radius).

  • pt: coordinates "latitude,longitude"
  • d: radial distance in kilometers, default 25 km. The minimum value is 5 km

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

Request example:
http://ws.cercalia.com/suggest/SuggestServlet?key=xxxxxxxxxxxx&t=avinguda%20diagonal%20200,%20barcelona&getype=st,ct&ctryc=ESP

Response:

The answer is always returned in JSON format.
The response is always returned with UTF-8 encoding.

Types of items returned by the suggestions API:

locality

If the strong>"id" field begins with 'CT', it is a locality.

Address (*)

If the strong>"id" field begins with 'ST', it is a street.

The street can also have the following optional fields:

  • "portal" Portal number. Appears when the number has been separated from the rest of the address.
  • "portal_disponible" Available portal number. Appears when the number has been separated from the rest of the address and conforms to the available portals for each address.
  • "portal_en" Indicates if the address was written in English by the user [true / false].
  • "codigo_postal" Indicates the postal code of the address, as long as it is available and / or a complete address (street and number) has been indicated.

(*) Important: The coordinates returned in each candidate are those of street default. To obtain the exact coordinates of the indicated portal number it is necessary to perform the address geocoding request.

 

Response Example:

{
   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"
         }
      ]
   }
}

 

STREET CROSSINGS & ADDRESS WITH REFERENCE TO SECOND STREET

he answer is equal to the address with the information of the second street of the crossing, plus an "intersection" element in each candidate, where the "intersection" element contains the information of the first street of the crossing, but with the coordinate "coordinate "of the crossing..

You can use it to search/ geocode two types of addresses:

  • Street crossings: Example: Calle de Diego de León / Velázquez, Madrid (España)
  • Exact address, referencing a street with which it crosses (system commonly used in countries such as Turkey or Colombia). Examples
    • Namik Kemal Sokak & Kocayol Caddesi 12, Bostanci (Turquía)
    • Carrera 69P & calle 70-63, Bogotá (Colombia)

To separate the first street from the second one, you can use the " & " o " / ", separator, with the spaces. If there are no spaces between the separator, it will be understood that it is part of the street name itself

Answer example:
"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
            }
         }
      ]
   }
}

GEOCODING REQUESTS

Request:

To geocode an address (get the exact coordinates of the portal detail), it is necessary to collect the suggestions response parameters of the selected candidate, and launch the request with these parameters:

"key"
Security key:

  • For WEB applications, use the same KEY as for the Cercalia Maps API
  • For all other applications (server, APP, ...), request a KEY to Nexus

"ctc"
Location code (localidad_id field from suggest response)

"stc"
Street code (calle_id field from suggest response)

"stnum"
Portal number (portal field)

It is mandatory to report all the codes obtained in the response. For some countries, the Postal Code may not be returned.

Example of request:
http://ws.cercalia.com/suggest/SuggestServlet?key=xxxxxxxxx&ctc=ESP17240207272367&stc=ESP030149000090298&stnum=17

Response:

The answer is always returned in JSON format.
The response is always returned with UTF-8 encoding.

The answer includes the coordinates, in geographical format. Example:

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

STREET CROSSINGS

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

For this case, it is NOT necessary to make the request for geocoding of addresses (although it can be done), since the response of the suggestion service already incorporates the coordinate of the street crossing

POINTS OF INTEREST (POI) SEARCH

Request:

She GET and POST methods are accepted.
The parameters must always be encoded in UTF-8.

"key"
Security key:

  • For WEB applications, use the same KEY as for the Cercalia Maps API
  • For all other applications (server, APP, ...), request a KEY from Nexus

"pois"
Always send "pois" with value to "1".

"t"
Text to search. It can contain the street, number, location, zip code, etc. The postal code acts as a limiter: in case of not finding matches, it broadens the search to the entire municipality belonging to the CP.

"nofuzzy"
Not to use fuzzy (search for similar words). Use the values ​​"Yes", "Y" or "1".

Optional filters:

  • ctryc: country code(Ex: ESP,FRA)
  • regc: region code - autonomous community (Ex: ESPMAD,ESPCAT)
  • subregc: subregion code - province (Ex:ESP08,EPS28)
  • munc: municipality code (Ex: ESP080193,ESP280796)
  • rsc: municipality / region / subregion / country code (replaces munc, subregc, regc and ctryc). Ex: ESP,ESPMAD,ESP08,ESP410917
  • rscp: municipality / region / subregion / country code prioritized. This filter, prioritizes the results in the specified regions, over the rest of the candidates, filling out the list of suggestions with the candidates in the prioritized region (whenever you find candidates), but does not delete the results from the rest regions or countries. This filter can be combined with the "rsc" filter to get a maximum filter of results beyond favorites. Ex: ESPVAL
    * rscp1 – rscp2 ...: If you need to prioritize the candidates in the list of preferred regions, the regions can be separated by separate parameters according to priority level: rscp1: maximum priority, rscp2: second priority level, ...
  • rsclp: municipality / region / subregion / country code prioritized. Not compatible with rscp filter. This filter prioritizes the results found in the specified regions more gently than "rscp": it only collects a maximum of 3 candidates with the highest scores from the specified regions, and does not eliminate those from the rest of the regions. This filter can be combined with the "rsc" filter, to obtain a maximum filter of results beyond the preferred ones. Ex: ESPVAL
    * rsclp1 – rsclp2 ...: municipality / region / subregion / country code prioritized. Not compatible with rscp filter. This filter, prioritizes smoother than "rscp" results in the specified regions: Only picks up to 3 top scoring candidates from the specified regions, and does not remove those from the rest of the regions. This filter can be combined with the "rsc" filter to get a maximum filter of results beyond favorites. Ex: ESPVAL * rscp1 - rscp2 ...: If you need to prioritize the candidates in the list of preferred regions, the regions can be separated by separate parameters according to priority rsclp1: maximum priority, rsclp2: second priority level, ...
  • id: POI code (ex: PESP724009000642061)
  • poicat (*): POI category code. Comma separated list. Ex::
    poicat=C005,C043
     

(*) poicat: in case of not specifying POI categories, the system looks for suggestions only among the categories marked by default in the category table. If you want to search in all categories, or certain ones, you must indicate this parameter.

 

Proximity filter

You can filter the results by proximity to a point (coordinate). It is a restrictive filter (only returns candidates that are within the radius).

  • pt: coordinates "latitude,longitude"
  • d: radial distance in kilometers, default 25 km. The minimum value is 5 km

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

Request example:
http://ws.cercalia.com/suggest/SuggestServlet?key=xxxxxxxxxxxx&pois=1&t=Museo%20del%20Prado%20Madrid&ctryc=ESP

Response:

The answer is always returned in JSON format..
The response is always returned with UTF-8 encoding..

Types of items returned by the suggestions API:

  • If the "id" field begins with "P" it is a point of interest (POI)..

List of POI categories (*):

(*) poicat: in case of not specifying POI categories, the system looks for suggestions only among the categories marked by default in the category table. If you want to search in all categories, or certain ones, you must indicate this parameter.

CODE DESCRIPTION INCLUDED IN DEFAULT SEARCH

C012

Public administration

SI

C005

Airport

SI

C037

Major tourist attraction

SI

C023

Camping

SI

C036

Casino

SI

C010

Mall

SI

C043

Convention Center

SI

D00ESC

School

SI

C004

Train station

SI

C015

Stadium / Sports Center

SI

C046

Golf

SI

C009

Hospital / Clinic

SI

C013

Hotel

SI

C030

Museum

SI

C112

Public transport stop, uncategorized

SI

C045

Theme park

SI

C044

Leisure port, sports port

SI

C031

Theater

SI

C016

Airport access

SI

C006

Ferry Terminal

SI

C027

College

SI

C048

Zoo

SI

C076

Bed & Breakfast

SI

C047

Library

SI

D00CAP

Primary Assistance Center (Spain only)

SI

C032

Sports Center

SI

C025

Movie theater/p>

SI

C070

Ski resort

SI

C110

Industry

SI

C035

Cult place

SI

C107

Market

SI

C041

Opera

SI

C074

Water park

SI

C072

Botanic Park

SI

C075

Wildlife park

SI

C039

Parks and recreation areas

SI

C038

Ice skating rink

SI

C022

Beach

SI

C050

Industrial Estate

SI

C077

Hotel Resort

SI

C042

Concert hall

SI

C079

Military airport

 

C105

Rent a car

 

C007

Parking

 

C108

Parking for trucks

 

C002

Parking & rest area

 

C003

Service area

 

C106

Bank

 

C080

Airfield

 

C029

Tourist Information Center

 

C033

Police station

 

C018

Embassy

 

C026

Pharmacy

 

C001

Fuel station

 

D00GUA

Nursery schools (Spain)

 

C109

Car wash

 

C049

Subway

 

C040

Courthouse

 

C083

Bus stop

 

C081

Intercity bus stop

 

C051

Tram stop

 

D00BUS

Urban BUS stops

 

C111

Car rental parking

 

C019

Border crossing

 

C020

Mountain peak

 

C034

Swimming pool

 

C017

Mountain's Port

 

D104

Electric vehicle charging points

 

C014

Restaurant

 

C078

Supermarket & Hypermarket

 

C028

Mechanical workshop

 

D00TRA

Trams (Spain)

 

C008

Car sales

 

 

Example response:/p>

{
   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:"[email protected]",
            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

If "status" is 0, the answer is correct.

Error response: when "status" other than 0.

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

OPTIONAL: USE SQUARE BRACKETS FOR DIFFERENCIATE THE LOCALITY AND THE REST OF THE SEARH TEXT

Request:

Request Parameters:

"t" = Text to search. It can contain the address (street, number, zip code). And in this case the locality name is in square brackets at the end of the text. The part that goes after the location will be ignored.

It is important to keep in mind that using this search system you only have to include the address and the population, since it looks for concordance only in the street and town fields.

Example:

  • Calle de Barcelona 16 [Madrid]   ->  &t=Calle+de+Barcelona+16,%20%5BMadrid%5D
  • Calle de Barcelona 16, 28012 [Madrid]   ->  t=Calle+de+Barcelona+16,%2028012%20%5BMadrid%5D

The other parameters are the same as the previous requests for suggestions.

Response:

Same as the rest of the previous requests for suggestions.