This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Suggest API

Comprehensive documentation for integrating Cercalia’s Suggest API into your applications.

1: Suggest Requests
2: Geocoding Address Requests
3: POI Requests
4: Bracket locality
5: Examples requests
6: Languages
7: Errors

Web Services

Documentation about the Suggest functionality available through the HTTP-JSON web service of the CERCALIA platform.

Base URL: https://lb.cercalia.com/suggest/SuggestServlet?key=<API_KEY>
API Key: The security key is the same as the one used for the Cercalia Maps API.

Request Methods

GET: Parameters are sent in the URL.
POST: Parameters are sent in the body of the request.

Response Format

Responses are returned in JSON format.

Introduction to the Cercalia Suggest API

The Suggest web service provides functionality for querying addresses, localities, and points of interest. This service allows you to:

Suggestion Requests:
- Includes addresses, localities, and points of interest (POIs).
- Does not include precise coordinates for addresses. A subsequent geocoding request is required to obtain detailed address coordinates.
Geocoding Requests:
- Retrieve the X and Y (longitude and latitude) coordinates of a specific address.

Key Details

Suggestion requests already include the coordinates for each candidate, except for addresses, which only return the default street coordinate.
For detailed portal coordinates, an additional geocoding request to the web service is required.

Web Service URL

https://lb.cercalia.com/suggest/SuggestServlet?

1 - Suggest Requests

Comprehensive documentation for integrating Cercalia’s Suggest API into your applications.

Request

Request Methods

Both GET and POST methods are supported.
All parameters must be UTF-8 encoded.

Request Parameters

Parameter	Description	Required	Values/Notes
`key`	Security key.	Yes	For web applications, use the same key as the Cercalia Maps API. For other applications (server, app, etc.), request a key from Nexus.
`t`	Text to search. Can include street, number, locality, postal code, etc. The postal code acts as a limiter; if no matches are found, the search expands to the entire municipality associated with the postal code.	Yes	Example: `t=Carrer+de+Mallorca`

Optional Parameters

Parameter	Description	Values/Notes
`stnum`	Address number to search.	If provided, numeric values in `t` will be interpreted as part of the street/locality name, not as an address number.
`alllike`	Use `like` for all words.	Accepted values: `Yes`, `Y`, or `1`.
`nofuzzy`	Disable fuzzy search (search for similar words).	Accepted values: `Yes`, `Y`, or `1`.
`getype`	Filter results by element type.	Comma-separated list of values: - `st`: Streets - `ct`: Localities - `all`: Returns all types (default if not specified). Example: `getype=st,ct`.

This structure provides a clear and professional overview of the parameters required for Suggest API requests. Let me know if further refinements are needed!

Optional Filters

Parameter	Description	Example / Notes
`ctryc`	Country code.	Example: `ESP`, `FRA`.
`regc`	Region code (community).	Example: `ESPMAD`, `ESPCAT`.
`subregc`	Subregion code (province).	Example: `ESP08`, `ESP28`.
`munc`	Municipality code.	Example: `ESP080193`, `ESP280796`.
`rsc`	Code for municipality/region/subregion/country (replaces `munc`, `subregc`, `regc`, and `ctryc`).	Example: `ESP`, `ESPMAD`, `ESP08`, `ESP410917`.
`rscp`	Preferred code for municipality/region/subregion/country. Prioritizes results in specified regions but does not exclude others. Can be combined with `rsc` for broader results.	Example: `ESPVAL`. Supports multiple levels of priority (`rscp1`, `rscp2`, etc.).
`rsclp`	Similar to `rscp` but with softer prioritization. Retrieves up to 3 top-scoring candidates from specified regions without excluding others.	Example: `ESPVAL`. Supports multiple levels of priority (`rsclp1`, `rsclp2`, etc.).
`excluderegions`	Boolean parameter to exclude region names from the search. Recommended when using radius filtering or when applying `rsc` or `rscp` filters.	Possible values: `1` to exclude region filters.
`stc`	Street code.	Example: `ESP280796000099043`.
`hnrt`	Applies tolerance to the house number search, prioritizing addresses containing the searched number within a tolerance margin (default is 50 numbers for most locations).	Default value: `1` (apply tolerance). Set to `0` to disable.
`excluderegions=1`	Prevents the inclusion of region name filters in the search.	Optional. Useful when filtering by radius or using `rsc`/`rscp` parameters.
`lang`	Preferred language codes. Specifies the languages in which suggestions should be returned, if available (ISO 3-digit codes).	Example: `lang=baq,spa` (prioritizes Basque, then Spanish).
`pt`	Specifies the latitude and longitude coordinates to be used as a reference point for distance calculations.	Example: `37.416217,-122.085905`
`d`	Defines the radius in kilometers used for selecting locations within this distance from the reference point `pt`. The minimum allowed value is 5 kilometers.	Example: `50` (Radius of 50 km)

Notes on Language Codes

Use ISO 3-digit language codes to specify your preference.
Example: lang=baq,spa will prioritize Basque and fallback to Spanish if unavailable.
Table with available languages: languages

Response

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

Types of elements returned by the Suggest API:

Locality: If the “id” field starts with ‘CT’, it is a locality.
Addresses: If the “id” field starts with ‘ST’, it is a street. The street may also have optional fields such as “portal_min”, “portal_max”, “portal”, “portal_disponible”, and/or “portal_en”.
- “portal”: Indicates the house number when separated from the rest of the address.
- “portal_disponible”: Indicates the available house number when separated and adjusted to the available numbers for each address.
- “portal_en”: Indicates if the user has written the address in English format [true/false].
- “codigo_postal”: Indicates the postal code of the address, provided it is available and a complete address (street and number) has been specified.

Important: The coordinates returned for each candidate are the default for the street. To obtain the exact coordinates of a specified house number, a geocoding request is necessary.

Example Response:

{
  "responseHeader": {
    "status": 0,
    "QTime": 88,
    "params": {
      "ctryc": "ESP",
      "getype": "st,ct",
      "key": "YOUR_API_KEY",
      "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 Intersections & Addresses with Reference to a Second Street:

The response is similar to that for addresses but includes information about the second street in the intersection, along with an intersection element in each candidate. This element contains information about the first street, with the coord field representing the intersection point.

This allows for searching/geocoding two types of addresses:

Street Intersections: e.g., Calle de Diego de León / Velázquez, Madrid (Spain)
Exact Address Referencing a Cross Street: Common in countries like Turkey or Colombia. e.g., Namik Kemal Sokak & Kocayol Caddesi 12, Bostanci (Turkey) or Carrera 69P & calle 70-63, Bogotá (Colombia)

To separate the first street from the second, use the separator & or /, including spaces.

2 - Geocoding Address Requests

Detailed documentation on how to perform geocoding address requests using Cercalia’s Suggest API.

Geocoding Address Requests

To obtain the exact coordinates of a specific address (including house number), you need to use the parameters returned from the selected candidate in the suggestions response and make a geocoding request with these parameters:

Request Parameters

Parameter	Description	Example
`cmd`	Fixed value `cand`	`cand`
`adr`	Street name (including house number)	`avinguda diagonal 200`
`ctn`	Locality	`barcelona`
`pcode`	Postal code	`08018`
`ctryc`	Country code (ISO 3 characters)	`ESP`
`detcand`	Fixed value `1`	`1`
`priorityfilter`	Fixed value `1`	`1`

Example Request:

https://lb.cercalia.com/services/json?key=YOUR_API_KEY&cmd=cand&adr=avinguda diagonal 200&ctn=barcelona&ctryc=ESP&detcand=1&priorityfilter=1

Response

The service returns a JSON object containing the geocoded address with its exact coordinates.

Example Response:

{
  "cercalia": {
    "cmd": "cand",
    "version": "1",
    "candidates": {
      "num": "1",
      "pos": "0",
      "total": "1",
      "candidate": {
        "desc": "Avinguda Diagonal, 200 (Barcelona)",
        "name": "Avinguda Diagonal",
        "source": "cercalia",
        "ge": {
          "id": "ESP080193000092155",
          "name": "Avinguda Diagonal",
          "prefix": "Avinguda",
          "sname": "Diagonal",
          "type": "adr1",
          "name": "Avinguda Diagonal, 200",
          "housenumber": "200",
          "postalcode": {
            "country_id": "ESP",
            "id": "08018"
          },
          "city": {
            "id": "ESP17240008430951",
            "value": "Barcelona"
          },
          "municipality": {
            "id": "ESP080193",
            "value": "Barcelona"
          },
          "subregion": {
            "id": "ESP08",
            "value": "Barcelona"
          },
          "region": {
            "id": "ESPCAT",
            "value": "Catalunya"
          },
          "country": {
            "id": "ESP",
            "value": "Spain"
          },
          "coord": {
            "x": "2.165638",
            "y": "41.387917"
          }
        }
      }
    },
    "server": "http://cercalia-tomcat-lbs-instance3:8080"
  }
}

Note: Replace YOUR_API_KEY with your actual API key provided by Cercalia.

For more detailed information, refer to the Cercalia Suggest API Documentation.

3 - POI Requests

Detailed documentation on how to perform POI suggestion requests using Cercalia’s Suggest API.

Requests

To obtain suggestions for Points of Interest (POIs), you can use the following parameters in your request:

Request Parameters

Parameter	Description	Example
`key`	Security key: For web applications, use the same KEY as for the Cercalia Maps API. For other applications (server, APP, …), request a KEY from Nexus.	`your_api_key`
`t`	Text to search. Can contain street, number, locality, postal code, etc. The postal code acts as a limiter: if no matches are found, it expands the search to the entire municipality belonging to the postal code.	`restaurant near central park`
`getype`	Filter by element types. Comma-separated list. Possible values: `st` for Streets, `ct` for Localities, `poi` for Points of Interest, `all` returns all types (equivalent to not sending the parameter).	`poi`
`nofuzzy`	Enables exact matches only. Avoids “fuzzy” matching algorithms for more precise results.	`true`

Optional Filters

Parameter	Description	Example
`ctryc`	Country code	`ESP`
`regc`	Region code - community	`ESPMAD`
`subregc`	Subregion code - province	`ESP08`
`munc`	Municipality code	`ESP080193`
`rsc`	Code for municipality/region/subregion/country (replaces munc, subregc, regc, and ctryc).	`ESP,ESP08,ESPCAT`
`rscp`	Preferred code for municipality/region/subregion/country. Prioritizes results in specified regions over others. Can be combined with `rsc` for broader filtering.	``
`rsclp`	Preferred code for municipality/region/subregion/country. Prioritizes results in specified regions more softly than `rscp`. Can be combined with `rsc` for broader filtering.	``
`pt`	Coordinate “lat,lon” for proximity filtering.	`40.7128,-74.0060`
`d`	Radial distance in kilometers for proximity filtering. Default is 25 km; minimum is 5 km.	`10`
`poicat`	Filters POIs by category. Uses category codes, which will be detailed in a separate table.	`C005,C043`

Example Requests

https://lb.cercalia.com/suggest/SuggestServlet?key=YOUR_API_KEY&pois=1&t=Museo%20del%20Prado%20Madrid&ctryc=ESP

Response

The response is returned in JSON format with UTF-8 encoding. It includes a list of POI suggestions matching the search criteria.

Example response

{
   responseHeader:{
      status:0,
      QTime:23,
      params:{
         ctryc:"ESP",
         key:"YOUR_API_KEY",
         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
         }
      ]
   }
}

List of POI Categories (*)

(*) poicat: If no POI categories are specified, the system will only search for suggestions within the default categories marked in the category table. If you want to search in all categories or specific ones, you must indicate them using this parameter.

Code	Description	Included in Default Search
C012	Public Administration	Yes
C005	Airport	Yes
C037	Major Tourist Attraction	Yes
C023	Camping	Yes
C036	Casino	Yes
C010	Shopping Center	Yes
C043	Convention Center	Yes
D00ESC	School	Yes
C004	Train Station	Yes
C015	Stadium / Sports Center	Yes
C046	Golf Course	Yes
C009	Hospital / Clinic	Yes
C013	Hotel	Yes
C030	Museum	Yes
C112	Public Transport Stop (Uncategorized)	Yes
C045	Amusement Park	Yes
C044	Marina	Yes
C031	Theater	Yes
C016	Airport Access	Yes
C006	Ferry Terminal	Yes
C027	University	Yes
C048	Zoo	Yes
C076	Bed & Breakfast	Yes
C047	Library	Yes
D00CAP	Primary Care Center (Spain only)	Yes
C032	Sports Center	Yes
C025	Cinema	Yes
C070	Ski Station	Yes
C110	Industry	Yes
C035	Place of Worship	Yes
C107	Market	Yes
C041	Opera	Yes
C074	Water Park	Yes
C072	Botanical Garden	Yes
C075	Wildlife Park	Yes
C039	Park and Recreational Area	Yes
C038	Ice Rink	Yes
C022	Beach	Yes
C050	Industrial Zone	Yes
C077	Resort Hotel	Yes
C042	Concert Hall	Yes
C079	Military Airport	No
C105	Vehicle Rental	No
C007	Parking Lot	No
C108	Truck Parking	No
C002	Rest Area	No
C003	Service Area	No
C106	Bank	No
C080	Airfield	No
C029	Tourist Information Center	No
C033	Police Station	No
C018	Embassy	No
C026	Pharmacy	No
C001	Gas Station	No
D00GUA	Nursery (Spain)	No
C109	Car Wash	No
C049	Subway	No
C040	Courthouse	No
C083	Bus Stop	No
C081	Intercity Bus Stop	No
C051	Tram Stop	No
D00BUS	Urban Bus Stops	No
C111	Vehicle Rental Parking	No
C019	Border Crossing	No
C020	Mountain Peak	No
C034	Swimming Pool	No
C017	Mountain Pass	No
D104	EV Charging Points	No
C014	Restaurant	No
C078	Supermarket & Hypermarket	No
C028	Mechanical Workshop	No
D00TRA	Trams (Spain)	No
C056	Car Sales	No

4 - Bracket locality

Explanation on how to use brackets in the “t” parameter to differentiate the locality when searching with Cercalia’s Suggest API.

Optional: Using Brackets to Differentiate the Locality from the Rest of the Address

Request

Request Parameters:

Parameter	Description
`t`	Text to search. It can contain the address (street, number, postal code). The locality name is enclosed in square brackets at the end of the text. Any part of the text after the locality will be ignored.

It is important to note that when using this search method, you must include only the address and the locality, as it matches exclusively against the street and locality fields.

Examples:

Input: Calle de Barcelona 16 [Madrid]
Formatted Parameter: &t=Calle+de+Barcelona+16,%20%5BMadrid%5D
Input: Calle de Barcelona 16, 28012 [Madrid]
Formatted Parameter: &t=Calle+de+Barcelona+16,%2028012%20%5BMadrid%5D

The rest of the parameters are the same as in previous suggestion requests.

Response

The response format is identical to previous suggestion requests.

5 - Examples requests

Detailed and explained requests

Example Requests

Here are two examples of how to use the t parameter with locality enclosed in square brackets, explained step by step.

Example 1: Searching for an Address with a Locality

Scenario:

You want to search for “Calle de Barcelona 16” in the locality “Madrid”. Using brackets ensures the locality is properly recognized.

Request

https://lb.cercalia.com/suggest/SuggestServlet?key=your_api_key&t=Calle de Barcelona 16, [Madrid]

Explanation

t: Calle de Barcelona 16 [Madrid]
- The street name is “Calle de Barcelona 16”.
- The locality is specified as Madrid, enclosed in square brackets [Madrid].
The brackets ensure that the locality is matched, and anything after [Madrid] is ignored.

Example 2: Searching for an Address with a Postal Code and Locality

Scenario:

You want to search for “Calle de Barcelona 16, 28012” in the locality Madrid, while including the postal code.

Request

https://lb.cercalia.com/suggest/SuggestServlet?key=your_api_key&t=Calle de Barcelona 16, Madrid

Explanation

t: Calle de Barcelona 16, 28012 [Madrid]
- The street name is “Calle de Barcelona 16”.
- The postal code is 28012, and it’s included in the text.
- The locality is Madrid, enclosed in square brackets [Madrid].

Notes:

Replace your_api_key with the actual API key provided by Cercalia.

This format breaks down each request into an easily digestible explanation, making it clear what each parameter does and how it works.

6 - Languages

Suggest languages

Supported Language Codes

Language	Code
Arabic	ARA
Basque	BAQ
Catalan	CAT
Croatian	SCR
Czech	CZE
Danish	DAN
Dutch	DUT
English	ENG
Estonian	EST
Finnish	FIN
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

7 - Errors

Detailed documentation when error is returned

If status is 0, the response is correct.

Error response: when status is different from 0.

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