Geocoding
Comprehensive documentation for integrating Cercalia’s Geocoding API into your applications.
7 minute read
API Access
The Geocoding API allows you to convert physical addresses into geographic coordinates and vice-versa (address normalization). It is available via HTTP-JSON and XML services.
Base Service URLs:
- Supported methods: GET or POST
- Response formats: JSON / XML
Address Geocoding Service
The Address Geocoding service provides normalized address data and geographic coordinates for a given location.
Request Parameters
When using separate parameters for the address:
https://lb.cercalia.com/services/v2/json?cmd=cand&detcand=1&priorityfilter=1&key=YOUR_API_KEY
Report address with separate parameters:
| Code | Description |
|---|---|
adr | Address (including street name and house number) |
ctn | Locality |
pcode | Postal code |
rsn | Region name (optional) |
ctryc | Country code (ISO 3 characters) |
ctryn | Country name |
Optional parameter:
&fullsearch=3: Provides a more restrictive address search. When an address includes a postal code, the system verifies if the matched address belongs to that specific postal code. If they differ, the response returns normalization only up to the postal code level.
Example:
https://lb.cercalia.com/services/v2/json?cmd=cand&detcand=1&adr=diagonal 22&ctn=barcelona&ctryc=esp&key=YOUR_API_KEY
Report address with a single parameter:
| Code | Description |
|---|---|
mode | Fixed parameter |
fadr | Street name + house number + postal code + locality |
ctryc | Country code (ISO 3 characters) |
ctryn | Country name |
Example:
https://lb.cercalia.com/services/v2/json?cmd=cand&mode=1&detcand=1&cleanadr=1&fadr=provença 589, 08026 barcelona&ctryc=ESP&key=YOUR_API_KEY
Response
Response (in JSON format):
{
"cercalia": {
"@version": "1",
"candidates": {
"@num": "1",
"@pos": "0",
"@total": "1",
"@urlcandidates": "ctc=ESP0055169L&stc=ESP08019300000150160&stnum=589&ctryc=ESP",
"@urlcommon": "",
"candidate": [
{
"@desc": "Carrer de Provença, 589 (Barcelona)",
"@name": "Carrer de Provença, 589",
"@urlparams": "ctc=ESP0055169L&stc=ESP08019300000150160&stnum=589&pcode=08026",
"urlparams": {
"param": [
{
"@name": "ctc",
"@value": "ESP0055169L"
},
{
"@name": "stc",
"@value": "ESP08019300000150160"
},
{
"@name": "stnum",
"@value": "589"
},
{
"@name": "pcode",
"@value": "08026"
}
]
},
"ge": {
"@article": "de",
"@id": "ESP08019300000150160",
"@name": "Carrer de Provença",
"@prefix": "Carrer",
"@sname": "Provença",
"@type": "adr",
"name": {
"value": "Carrer de Provença, 589"
},
"housenumber": {
"value": "589"
},
"postalcode": {
"@country_id": "ESP",
"@id": "08026"
},
"city": {
"@id": "ESP0055169L",
"value": "Barcelona"
},
"district": {
"@id": "ESP080190803",
"value": "El Camp de l'Arpa del Clot"
},
"municipality": {
"@id": "ESP080193",
"value": "Barcelona"
},
"subregion": {
"@id": "ESP08",
"value": "Barcelona"
},
"region": {
"@id": "ESPCAT",
"value": "Catalunya"
},
"country": {
"@id": "ESP",
"value": "España"
},
"coord": {
"@x": "2.18246597",
"@y": "41.41042418"
}
}
}
],
"urlcommon": {},
"urlcandidates": {
"param": [
{
"@name": "ctc",
"@value": "ESP0055169L"
},
{
"@name": "stc",
"@value": "ESP08019300000150160"
},
{
"@name": "stnum",
"@value": "589"
},
{
"@name": "ctryc",
"@value": "ESP"
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
Response Parameters
| Code | Description |
|---|---|
name | Street name |
type | Geocoding level: Possible values: adr / adr1: Exact addressadr2: Address with nearest house number availablest: Street centerpc: Postal code center• ct: Locality center |
housenumber | House number |
postalcode | Postal code |
city | Locality name |
municipality | Municipality name |
subregion | Region name (level 1) |
region | Region name (level 2) |
country | Country |
coord | Address coordinates (x, y) |
In case of zero results, the service returns the message:
<cercalia version="1">
<error id="30006" type="Sistema Cercalia">No se han encontrado candidatos</error/>
</cercalia>
Road Milestone Geocoding Service
Available for Spain, France, Portugal, and Andorra.
Request Parameters
https://lb.cercalia.com/services/v2/json?cmd=cand&detcand=1&key=YOUR_API_KEY
Request example:
https://lb.cercalia.com/services/v2/json?cmd=cand&detcand=1&rdn=M-45&km=12&munn=&pcode=&subregn=Madrid&ctryc=ESP&key=YOUR_API_KEY
Response Parameters
| Code | Description |
|---|---|
rdn | Road name |
km | Milestone |
direction | Optional. Road milestone direction (increasing or decreasing). Only available for highways (high capacity road, with a median strip). Values: |
Increasing: A, ASC, I | |
Decreasing: D, DESC | |
Both: BOTH | |
munn | Municipality name (optional) |
pcode | Postal code (optional) |
subregn | Region name (optional) |
ctryc | Country code (ISO 3 characters) |
Response
- Single result
- Several candidates
Response example with single result:
{
"cercalia": {
"@cmd": "cand",
"@version": "1",
"candidates": {
"@num": "1",
"@pos": "0",
"@total": "1",
"@urlcandidates": "km=12&subregn=Madrid&rdn=M-45&ctryc=ESP",
"@urlcommon": "",
"candidate": [
{
"@desc": "M-45, pk 12 (Madrid)",
"@name": "M-45, Km. 12",
"@urlparams": "km=12&munc=ESP280796&rdc=M-45&direction=A",
"urlparams": {
"param": [
{
"@name": "km",
"@value": "12"
},
{
"@name": "munc",
"@value": "ESP280796"
},
{
"@name": "rdc",
"@value": "M-45"
},
{
"@name": "direction",
"@value": "A"
}
]
},
"ge": {
"@id": "M-45",
"@name": "M-45",
"@type": "rd",
"name": {
"value": "M-45, Km. 12"
},
"km": {
"value": "12"
},
"direction": {
"value": "A"
},
"postalcode": {
"@country_id": "ESP",
"@id": "28021"
},
"city": {
"@id": ""
},
"district": {
"@id": "ESP280791703",
"value": "Butarque"
},
"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.66226073",
"@y": "40.33810394"
}
}
}
],
"urlcommon": {},
"urlcandidates": {
"param": [
{
"@name": "km",
"@value": "12"
},
{
"@name": "subregn",
"@value": "Madrid"
},
{
"@name": "rdn",
"@value": "M-45"
},
{
"@name": "ctryc",
"@value": "ESP"
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
Response Parameters
| Code | Description |
|---|---|
name | Road name |
type | Geocoding level (“rd” = road) |
postalcode | Postal code |
subregion | Region name (level 1) |
region | Region name (level 2) |
country | Country |
coord | Milestone coordinates (x, y) |
In case of several candidates:
Step one: the service returns a list of candidates with basic information.
Step two: second request using the road code (collected from the ge_id = of the selected candidate): &rdc = (road code) parameter instead of & rdn = (road name). This step is necessary, since the coordinates returned in the case of more than one candidate are the default coordinates of the road, not the full address indicated.
Request example:
https://lb.cercalia.com/services/v2/json?cmd=cand&detcand=1&rdn=A231&km=13&pcode=&ctryc=ESP&key=YOUR_API_KEY
Step one - Response (in JSON format):
{
"cercalia": {
"@cmd": "cand",
"@version": "1",
"candidates": {
"@num": "2",
"@pos": "0",
"@total": "2",
"@urlcandidates": "km=13&rdn=A231&ctryc=ESP",
"@urlcommon": "pcode=",
"candidate": [
{
"@desc": "A-231, pk 13 (La Fresneda)",
"@name": "A-231, Km. 13",
"@urlparams": "km=13&munc=ESP441085&rdc=A-231&direction=A",
"urlparams": {
"param": [
{
"@name": "km",
"@value": "13"
},
{
"@name": "munc",
"@value": "ESP441085"
},
{
"@name": "rdc",
"@value": "A-231"
},
{
"@name": "direction",
"@value": "A"
}
]
},
"ge": {
"@id": "A-231",
"@name": "A-231",
"@type": "rd",
"name": {
"value": "A-231, Km. 13"
},
"km": {
"value": "13"
},
"direction": {
"value": "A"
},
"city": {
"@id": ""
},
"district": {
"@id": ""
},
"municipality": {
"@id": "ESP441085",
"value": "La Fresneda"
},
"subregion": {
"@id": "ESP44",
"value": "Teruel"
},
"region": {
"@id": "ESPARA",
"value": "Aragón"
},
"country": {
"@id": "ESP",
"value": "España"
},
"coord": {
"@x": "0.08860982",
"@y": "40.90650796"
}
}
},
{
"@desc": "A-231, pk 13 (Villanueva de las Manzanas)",
"@name": "A-231, Km. 13",
"@urlparams": "km=13&munc=ESP242186&rdc=A-231&direction=A",
"urlparams": {
"param": [
{
"@name": "km",
"@value": "13"
},
{
"@name": "munc",
"@value": "ESP242186"
},
{
"@name": "rdc",
"@value": "A-231"
},
{
"@name": "direction",
"@value": "A"
}
]
},
"ge": {
"@id": "A-231",
"@name": "A-231",
"@type": "rd",
"name": {
"value": "A-231, Km. 13"
},
"km": {
"value": "13"
},
"direction": {
"value": "A"
},
"city": {
"@id": ""
},
"district": {
"@id": ""
},
"municipality": {
"@id": "ESP242186",
"value": "Villanueva de las Manzanas"
},
"subregion": {
"@id": "ESP24",
"value": "León"
},
"region": {
"@id": "ESPCYL",
"value": "Castilla y León"
},
"country": {
"@id": "ESP",
"value": "España"
},
"coord": {
"@x": "-5.45942131",
"@y": "42.45782014"
}
}
}
],
"urlcommon": {
"param": [
{
"@name": "pcode",
"@value": ""
}
]
},
"urlcandidates": {
"param": [
{
"@name": "km",
"@value": "13"
},
{
"@name": "rdn",
"@value": "A231"
},
{
"@name": "ctryc",
"@value": "ESP"
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
Step two - Second request using the road code (collected from the ge_id = of the selected candidate): &rdc=A-231
https://lb.cercalia.com/services/v2/json?&cmd=cand&detcand=1&rdc=A-231&munc=ESP441085&km=13&pcode=&ctryc=ESP&key=YOUR_API_KEY
List of Cities related to a Postal Code
Request
Request example:
https://lb.cercalia.com/services/v2/json?cmd=prox&rqge=ctpcode&ctryc=ESP&pcode=40160&key=YOUR_API_KEY
Response Parameters
| Code | Description |
|---|---|
ctryc | Country code (ISO 3 characters) |
ctryn | Country name |
pcode | Postal code. Examples: “40160” (ESP), “3415-PT” “3415” (NLD), “2680-344” (PRT) |
Response
Response (in JSON format):
{
"cercalia": {
"@cmd": "prox",
"@version": "1",
"proximity": {
"@center": "-4.02483875,40.99183593",
"@num": "1",
"@type": "ctpcode",
"gelist": {
"@num": "2",
"@type": "ct",
"ge": [
{
"@id": "ESP0052174L",
"@name": "Torrecaballeros",
"municipality": {
"@id": "ESP402038",
"value": "Torrecaballeros"
},
"subregion": {
"@id": "ESP40",
"value": "Segovia"
},
"region": {
"@id": "ESPCYL",
"value": "Castilla y León"
},
"country": {
"@id": "ESP",
"value": "España"
},
"coord": {
"@x": "-4.02483875",
"@y": "40.99183593"
}
},
{
"@id": "ESP0052177L",
"@name": "Cabanillas del Monte",
"municipality": {
"@id": "ESP402038",
"value": "Torrecaballeros"
},
"subregion": {
"@id": "ESP40",
"value": "Segovia"
},
"region": {
"@id": "ESPCYL",
"value": "Castilla y León"
},
"country": {
"@id": "ESP",
"value": "España"
},
"coord": {
"@x": "-4.03178273",
"@y": "40.97703001"
}
}
]
}
},
"server": {
"value": "lb.cercalia.com"
},
"instance": {
"value": "http://master-cercalia-lbs-both-lines"
}
}
}
Response Parameters
| Code | Description |
|---|---|
id | City ID |
name | City name |
municipality | Municipality ID & name |
subregion id | Subregion ID & name |
region id | Region ID & name |
country id | Country ID & name |
coord | X,Y city center |