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

ParameterDescriptionExample
keySecurity 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
tText 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
getypeFilter 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
nofuzzyEnables exact matches only. Avoids “fuzzy” matching algorithms for more precise results.true

Optional Filters

ParameterDescriptionExample
ctrycCountry codeESP
regcRegion code - communityESPMAD
subregcSubregion code - provinceESP08
muncMunicipality codeESP080193
rscCode for municipality/region/subregion/country (replaces munc, subregc, regc, and ctryc).ESP,ESP08,ESPCAT
rscpPreferred code for municipality/region/subregion/country. Prioritizes results in specified regions over others. Can be combined with rsc for broader filtering.``
rsclpPreferred code for municipality/region/subregion/country. Prioritizes results in specified regions more softly than rscp. Can be combined with rsc for broader filtering.``
ptCoordinate “lat,lon” for proximity filtering.40.7128,-74.0060
dRadial distance in kilometers for proximity filtering. Default is 25 km; minimum is 5 km.10
poicatFilters POIs by category. Uses category codes, which will be detailed in a separate table.C005,C043

Example Requests

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.

CodeDescriptionIncluded in Default Search
C012Public AdministrationYes
C005AirportYes
C037Major Tourist AttractionYes
C023CampingYes
C036CasinoYes
C010Shopping CenterYes
C043Convention CenterYes
D00ESCSchoolYes
C004Train StationYes
C015Stadium / Sports CenterYes
C046Golf CourseYes
C009Hospital / ClinicYes
C013HotelYes
C030MuseumYes
C112Public Transport Stop (Uncategorized)Yes
C045Amusement ParkYes
C044MarinaYes
C031TheaterYes
C016Airport AccessYes
C006Ferry TerminalYes
C027UniversityYes
C048ZooYes
C076Bed & BreakfastYes
C047LibraryYes
D00CAPPrimary Care Center (Spain only)Yes
C032Sports CenterYes
C025CinemaYes
C070Ski StationYes
C110IndustryYes
C035Place of WorshipYes
C107MarketYes
C041OperaYes
C074Water ParkYes
C072Botanical GardenYes
C075Wildlife ParkYes
C039Park and Recreational AreaYes
C038Ice RinkYes
C022BeachYes
C050Industrial ZoneYes
C077Resort HotelYes
C042Concert HallYes
C079Military AirportNo
C105Vehicle RentalNo
C007Parking LotNo
C108Truck ParkingNo
C002Rest AreaNo
C003Service AreaNo
C106BankNo
C080AirfieldNo
C029Tourist Information CenterNo
C033Police StationNo
C018EmbassyNo
C026PharmacyNo
C001Gas StationNo
D00GUANursery (Spain)No
C109Car WashNo
C049SubwayNo
C040CourthouseNo
C083Bus StopNo
C081Intercity Bus StopNo
C051Tram StopNo
D00BUSUrban Bus StopsNo
C111Vehicle Rental ParkingNo
C019Border CrossingNo
C020Mountain PeakNo
C034Swimming PoolNo
C017Mountain PassNo
D104EV Charging PointsNo
C014RestaurantNo
C078Supermarket & HypermarketNo
C028Mechanical WorkshopNo
D00TRATrams (Spain)No
C056Car SalesNo
Last modified December 31, 2024: fix: response json geocoding (8b989c0)