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.

Last modified December 31, 2024: fix: response json geocoding (8b989c0)