Reverse Geocoding API
Comprehensive documentation for integrating Cercalia’s Reverse Geocoding API into your applications.
7 minute read
API Access
The Reverse Geocoding API converts geographic coordinates into human-readable addresses, administrative divisions, and specialized geographic identifiers (censal sections, SIGPAC parcels). It is available via HTTP-JSON and XML services.
Base Service URLs:
- Supported methods: GET or POST
- Response formats: JSON / XML
Reverse Geocoding
Request Parameters
Request example (single coordinate):
https://lb.cercalia.com/services/v2/json?cmd=prox&mocs=gdd&mo=37.777041,-3.785477&rqge=adr&key=YOUR_API_KEY
Batch request (multiple coordinates using molist):
https://lb.cercalia.com/services/v2/json?cmd=prox&mocs=gdd&molist=[37.77741,-3.785477],[37.87704,-3.78577]&rqge=adr&key=YOUR_API_KEY
Maximum 100 coordinates per batch request.
| Parameter | Description |
|---|---|
mocs | Coordinate system (gdd for WGS84 lat/lon). |
mo | Single coordinate (format: Y,X for geographical, X,Y for projected). |
molist | Multiple coordinates for batch processing (format: [Y1,X1],[Y2,X2],...). |
rqge | Level of geographic detail (see table below). |
Detail Level Options (rqge)
| Value | Description |
|---|---|
cadr | Complete address (street name only, no house number). |
adr | Full address including house number and road milestone (if available). |
st | Street or road name (no house number/milestone). |
ct | City/locality. |
pcode | Postal code. |
mun | Municipality. |
subreg | Sub-region (province/department). |
reg | Region (state/autonomous community). |
ctry | Country. |
Response Structure
{
"cercalia": {
"@cmd": "prox",
"@version": "1",
"proximity": {
"@num": "2",
"@type": "adr",
"molist": {
"@num": "2",
"mo": [
{
"@id": "",
"ge": {
"@article": "de",
"@dist": "23",
"@frc": "ep",
"@height": "496",
"@id": "ESP23050300001125465",
"@kmh": "50",
"@name": "Avenida de Madrid",
"@pos": "1",
"@prefix": "Avenida",
"@sname": "Madrid",
"@zonename": "Jaén",
"@zonetype": "U",
"housenumber": {
"value": "66"
},
"intersection": {
"@dist": "65",
"@id": "ESP23050300001349385",
"@name": "Calle Flores de Lemus",
"@prefix": "Calle",
"@sname": "Flores de Lemus",
"coord": {
"@x": "-3.78531196",
"@y": "37.77786263"
}
},
"postalcode": {
"@country_id": "ESP",
"@id": "23008"
},
"city": {
"@id": "ESP0008001L",
"value": "Jaén"
},
"municipality": {
"@id": "ESP230503",
"value": "Jaén"
},
"subregion": {
"@id": "ESP23",
"value": "Jaén"
},
"region": {
"@id": "ESPAND",
"value": "Andalucía"
},
"country": {
"@id": "ESP",
"value": "España"
},
"coord": {
"@x": "-3.78530298",
"@y": "37.77731361"
}
},
"coord": {
"@x": "-3.78547366",
"@y": "37.77741343"
}
},
{
"@id": "",
"ge": {
"@article": "de",
"@dist": "527",
"@frc": "cl",
"@height": "330",
"@id": "ESP23050300001521455",
"@kmh": "30",
"@name": "Camino de Torre del Campo a Villagordo",
"@pos": "2",
"@prefix": "Camino",
"@sname": "Torre del Campo a Villagordo",
"intersection": {
"@article": "de",
"@dist": "3477",
"@id": "ESP23050300001620824",
"@name": "Camino de Fuente del Rey a Grañena",
"@prefix": "Camino",
"@sname": "Fuente del Rey a Grañena",
"coord": {
"@x": "-3.80529049",
"@y": "37.85770477"
}
},
"postalcode": {
"@country_id": "ESP",
"@id": "23009"
},
"city": {
"@id": "ESP0008050L",
"value": "Villar de Cuevas"
},
"municipality": {
"@id": "ESP230503",
"value": "Jaén"
},
"subregion": {
"@id": "ESP23",
"value": "Jaén"
},
"region": {
"@id": "ESPAND",
"value": "Andalucía"
},
"country": {
"@id": "ESP",
"value": "España"
},
"coord": {
"@x": "-3.78174565",
"@y": "37.87505272"
}
},
"coord": {
"@x": "-3.7857701",
"@y": "37.87703935"
}
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
Where:
| Code | Description |
|---|---|
dist | Distance in meters between coordinate and street |
kmh | Theoretical maximum speed in the road segment (source: TomTom). In Anglo-Saxon countries, this value is in miles per hour (not km/h) |
name | Street name (prefix + article + name) |
prefix | Street name prefix |
sname | Street name |
article | Article |
housenumber | House number (if available) |
height | Road point height, in meters |
zonetype | Zone type: urban (“U”) or industrial (“I”) |
zonename | Zone name (city or industrial area) |
district | District name (infra-municipal division, only available in some countries) |
municipality | Municipality (official ID and name) |
subregion | Subregion (official ID and name) |
region | Region (official ID and name) |
country | Country (official ID and name) |
In addition, is avialiable the node corresponding to the closest road junction
Road example:
<cercalia cmd="prox" version="1">
<proximity center="-404736,4937053" num="1" type="adr">
<gelist num="1" type="adr">
<location>
<municipality id="ESP281296">San Agustín del Guadalix</municipality>
<subregion id="ESP28">Madrid</subregion>
<region id="ESPMAD">Comunidad de Madrid</region>
<country id="ESP">España</country>
</location>
<ge dist="0" frc="na2" height="666" kmh="90" name="M-104" pos="1">
<km>2</km>
<postalcode country_id="ESP" id="28750"/>
<city dist="2225" id="ESP17240002420619">San Agustín del Guadalix</city>
<municipality id="ESP281296">San Agustín del Guadalix</municipality>
<subregion id="ESP28">Madrid</subregion>
<region id="ESPMAD">Comunidad de Madrid</region>
<country id="ESP">España</country>
<coord x="-404736" y="4937053"/>
</ge>
</gelist>
</proximity>
</cercalia>
Where the parameters are the same as in the case of street, with the exception of the records that refer to the road.
| Code | Description |
|---|---|
Name | Road number/code |
km | Milestone (available in France, Spain, and Portugal) |
direction | Road direction (only available for highways): A (increasing milestone) - D (decreasing milestone) |
frc | Road type |
Frc values:
| frc | Road type |
|---|---|
ap | Toll road - highway |
av | Dual carriageway |
na1 | First level road |
a2 | Second level road |
pl | Third level road |
ep | Main street |
cl | Secondary street |
pt | Pedestrian street |
Get the localities / regions that intersect a polygon
Request
Example:
https://lb.cercalia.com/services/v2/json?cmd=prox&rqge=mun&cs=4326&wkt=POLYGON((2.149028778076172%2041.39586980544921,2.146625518798828%2041.41930231731321,2.1816444396972656%2041.41981722266227,2.1813011169433594%2041.398187683195694,2.149028778076172%2041.39586980544921))&key=YOUR_API_KEY
Where:
| Code | Description |
|---|---|
cs | 4326 Polygon coordinate system. 4326 = geographical coordinates (LonLat) |
wkt | Polygon, in WKT format |
rqge | Detail level |
rqge values:
| rqge | desc |
|---|---|
ct | Locality |
mun | Municipality |
subreg | Subregion |
reg | Region |
Response
{
"cercalia": {
"@cmd": "prox",
"@version": "1",
"proximity": {
"@buffer": "0.0",
"@cs": "4326",
"@tolerance": "0.0",
"@type": "mun",
"@wkt": "POLYGON((2.149028778076172 41.39586980544921,2.146625518798828 41.41930231731321,2.1816444396972656 41.41981722266227,2.1813011169433594 41.398187683195694,2.149028778076172 41.39586980544921))",
"gelist": {
"@num": "1",
"@type": "mun",
"ge": [
{
"@id": "ESP080193",
"@name": "Barcelona",
"@pos": "1",
"subregion": {
"@id": "ESP08",
"value": "Barcelona"
},
"region": {
"@id": "ESPCAT",
"value": "Catalunya"
},
"country": {
"@id": "ESP",
"value": "España"
},
"coord": {
"@x": "2.1699165",
"@y": "41.38791358"
}
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
Get Censal Section from Coordinate (Spain Only)
Request Parameters
Example:
https://lb.cercalia.com/services/v2/json?cmd=prox&mo=40.3446890,-3.653151816&mocs=gdd&rqpoicats=d00seccen&key=YOUR_API_KEY
| Parameter | Description |
|---|---|
mo | Coordinate (format: Y,X for geographical, X,Y for projected). |
mocs | Coordinate system (gdd for WGS84). |
rqpoicats | Use d00seccen to query censal sections. |
Response Structure
{
"cercalia": {
"@cmd": "prox",
"@version": "1",
"proximity": {
"@center": "-3.65315182,40.34468901",
"@num": "1",
"@type": "poi",
"poilist": {
"@num": "1",
"poi": [
{
"@category_id": "D00SECCEN",
"@dist": "0",
"@geometry": "Z",
"@id": "D00SECCEN#DC00SC2807918002",
"@pos": "1",
"@subcategory_id": "-1",
"name": {
"value": "2807918002"
},
"info": {
"value": "2807918002"
},
"ge": {
"street": {
"@id": "UNKNOWN"
},
"city": {
"@id": "UNKNOWN",
"value": "Madrid"
},
"municipality": {
"@id": "ESP280796",
"value": "Madrid"
},
"subregion": {
"@id": "ESP28",
"value": "Madrid"
},
"region": {
"@id": "ESPMAD",
"value": "Comunidad de Madrid"
},
"country": {
"@id": "ESP",
"value": "España"
}
},
"coord": {
"@x": "-3.65200197",
"@y": "40.35683327"
}
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
| Field | Description |
|---|---|
name | Censal section identifier. |
info | Censal section identifier. |
Get SIGPAC Parcel from Coordinate (Spain Only)
Request Parameters
Example:
https://lb.cercalia.com/services/v2/json?cmd=prox&mo=41.426362180,2.038241447&mocs=gdd&rqpoicats=d00sigpac&key=YOUR_API_KEY
| Parameter | Description |
|---|---|
mo | Coordinate (format: Y,X for geographical, X,Y for projected). |
mocs | Coordinate system (gdd for WGS84). |
rqpoicats | Use d00sigpac to query SIGPAC parcels. |
Response Structure
Format:
{
"cercalia": {
"@cmd": "prox",
"@version": "1",
"proximity": {
"@center": "2.03824145,41.42636218",
"@num": "1",
"@type": "poi",
"poilist": {
"@num": "1",
"poi": [
{
"@category_id": "D00SIGPAC",
"@dist": "0",
"@geometry": "Z",
"@id": "D00SIGPAC#D00_08122_0_0_4_9000_1",
"@pos": "1",
"@subcategory_id": "-1",
"name": {
"value": "08122:0:0:4:9000:1"
},
"info": {
"value": "08122|ZU|19.254569471||0"
},
"ge": {
"street": {
"@id": "UNKNOWN"
},
"city": {
"@id": "UNKNOWN",
"value": "Molins de Rei"
},
"municipality": {
"@id": "ESP081234",
"value": "Molins de Rei"
},
"subregion": {
"@id": "ESP08",
"value": "Barcelona"
},
"region": {
"@id": "ESPCAT",
"value": "Catalunya"
},
"country": {
"@id": "ESP",
"value": "España"
}
},
"coord": {
"@x": "2.0397596",
"@y": "41.42864741"
}
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
Where:
| Code | Description |
|---|---|
name | SIGPAC parcel ID |
info | SIGPAC parcel info, with this format: |
field1|field2|field3|field4|field5 | |
field1 = municipality ID (INE) | |
field2 = parcel usage | |
field3 = parcel extension (Ha) | |
field4 = vulnerable area type | |
field5 = vulnerable area code |
Get the Time Zone from a coordinate
Request
Example:
https://lb.cercalia.com/services/v2/json?cmd=prox&mocs=gdd&mo=52.252025183,20.995254141&rqge=timezone&clientid=0123456789&datetime=2019-09-27T14:30:12Z&key=YOUR_API_KEY
Where:
| Code | Description |
|---|---|
mo | Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (Mercator, UTM, etc). |
datetime | Day and time to check (optional). If used, returns the local time in the region where the coordinates are located. |
Response
{
"cercalia": {
"@cmd": "prox",
"@version": "1",
"proximity": {
"@center": "20.99525414,52.25202518",
"@num": "1",
"@type": "timezone",
"gelist": {
"@num": "1",
"@type": "timezone",
"ge": [
{
"@daylightsavingtime": "3600000",
"@dist": "0",
"@id": "Europe/Warsaw",
"@localdatetime": "2019-09-27T16:30:12+02:00",
"@name": "Central European Summer Time",
"@pos": "1",
"@utcdatetime": "2019-09-27T14:30:12Z",
"@utctimeoffset": "3600000"
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
Where:
| Code | Description |
|---|---|
id | Time zone ID |
name | Time zone name |
localdatetime | Local time |
utcdatetime | UTC time |
utctimeoffset | Offset between local time and UTC time |
daylightsavingtime | Returns if this date is in summer or winter time |