Geocoding

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

Web services

Geocoding API documentation, available via HTTP-JSON/XML service.

URL base service:

HTTP requests in GET or POST
Response in JSON / XML format

Address geocoding service

Address geocodinig service: get the geocoding and address data normalized.

Request

Fixed parameters:

https://lb.cercalia.com/services/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. In case of indicating an address including the postal code, check if the address found is in the indicated postal code. If it is different, normalization up to postal code is returned in response.

Example:

https://lb.cercalia.com/services/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/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": {
        "param": [
          {
            "name": "ctc",
            "value": "ESP0055169L"
          },
          {
            "name": "stc",
            "value": "ESP08019300000150160"
          },
          {
            "name": "stnum",
            "value": "589"
          },
          {
            "name": "ctryc",
            "value": "ESP"
          }
        ]
      },
      "urlcommon": {
        
      },
      "candidate": [
        {
          "desc": "Carrer de Provença, 589 (Barcelona)",
          "name": "Carrer de Provença, 589",
          "urlparams": {
            "param": [
              {
                "name": "ctc",
                "value": "ESP0055169L"
              },
              {
                "name": "stc",
                "value": "ESP08019300000150160"
              },
              {
                "name": "stnum",
                "value": "589"
              },
              {
                "name": "pcode",
                "value": "08026"
              }
            ]
          },
          "ge": {
            "article": "de",
            "id": "ESP08019300000150160",
            "name": {
              "$valor": "Carrer de Provença, 589"
            },
            "prefix": "Carrer",
            "sname": "Provença",
            "type": "adr",
            "housenumber": {
              "$valor": "589"
            },
            "postalcode": {
              "country_id": "ESP",
              "id": "08026"
            },
            "city": {
              "id": "ESP0055169L",
              "$valor": "Barcelona"
            },
            "district": {
              "id": "ESP080190803",
              "$valor": "El Camp de l'Arpa del Clot"
            },
            "municipality": {
              "id": "ESP080193",
              "$valor": "Barcelona"
            },
            "subregion": {
              "id": "ESP08",
              "$valor": "Barcelona"
            },
            "region": {
              "id": "ESPCAT",
              "$valor": "Catalunya"
            },
            "country": {
              "id": "ESP",
              "$valor": "España"
            },
            "coord": {
              "x": "2.18246597",
              "y": "41.41042418"
            }
          }
        }
      ]
    },
    "server": {
      "$valor": "ws.cercalia.com"
    },
    "instance": {
      "$valor": "http://cercalia-lbs-both-lines"
    }
  }
}

Where:

Code	Description
`name`	Street name
`type`	Geocoding level
`adr/adr1`	Exact address
`adr2`	Address with nearest house number available
`st`	Street center
`pc`	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 (avaliable for Spain, France, Portugal and Andorra)

Request

Fixed parameters:

https://lb.cercalia.com/services/json?cmd=cand&detcand=1&key=YOUR_API_KEY

Request example:

https://lb.cercalia.com/services/json?cmd=cand&detcand=1&rdn=M-45&km=12&munn=&pcode=&subregn=Madrid&ctryc=ESP&key=YOUR_API_KEY

Where:

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">
	<ge id="ESPM-45_MAD" name="M-45" type="rd">
	  <name>M-45, Km. 12.0</name>
	  <postalcode country_id="ESP" id="28051" />
	  <city id="" />
	  <municipality id="" />
	  <subregion id="ESP28">Madrid</subregion>
	  <region id="ESPMAD">Comunidad de Madrid</region>
	  <country id="ESP">España</country>
	  <coord x="-3.653151816470334" y="40.34468901375571" />
	</ge>
  </cercalia>

Where:

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/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": {
        "param": [
          {
            "name": "km",
            "value": "13"
          },
          {
            "name": "rdn",
            "value": "A231"
          },
          {
            "name": "ctryc",
            "value": "ESP"
          }
        ]
      },
      "urlcommon": {
        "param": [
          {
            "name": "pcode",
            "value": ""
          }
        ]
      },
      "candidate": [
        {
          "desc": "A-231, pk 13 (La Fresneda)",
          "name": "A-231, Km. 13",
          "urlparams": {
            "param": [
              {
                "name": "km",
                "value": "13"
              },
              {
                "name": "munc",
                "value": "ESP441085"
              },
              {
                "name": "rdc",
                "value": "A-231"
              },
              {
                "name": "direction",
                "value": "A"
              }
            ]
          },
          "ge": {
            "id": "A-231",
            "name": {
              "$valor": "A-231, Km. 13"
            },
            "type": "rd",
            "km": {
              "$valor": "13"
            },
            "direction": {
              "$valor": "A"
            },
            "city": {
              "id": ""
            },
            "district": {
              "id": ""
            },
            "municipality": {
              "id": "ESP441085",
              "$valor": "La Fresneda"
            },
            "subregion": {
              "id": "ESP44",
              "$valor": "Teruel"
            },
            "region": {
              "id": "ESPARA",
              "$valor": "Aragón"
            },
            "country": {
              "id": "ESP",
              "$valor": "España"
            },
            "coord": {
              "x": "0.08860982",
              "y": "40.90650796"
            }
          }
        },
        {
          "desc": "A-231, pk 13 (Villanueva de las Manzanas)",
          "name": "A-231, Km. 13",
          "urlparams": {
            "param": [
              {
                "name": "km",
                "value": "13"
              },
              {
                "name": "munc",
                "value": "ESP242186"
              },
              {
                "name": "rdc",
                "value": "A-231"
              },
              {
                "name": "direction",
                "value": "A"
              }
            ]
          },
          "ge": {
            "id": "A-231",
            "name": {
              "$valor": "A-231, Km. 13"
            },
            "type": "rd",
            "km": {
              "$valor": "13"
            },
            "direction": {
              "$valor": "A"
            },
            "city": {
              "id": ""
            },
            "district": {
              "id": ""
            },
            "municipality": {
              "id": "ESP242186",
              "$valor": "Villanueva de las Manzanas"
            },
            "subregion": {
              "id": "ESP24",
              "$valor": "León"
            },
            "region": {
              "id": "ESPCYL",
              "$valor": "Castilla y León"
            },
            "country": {
              "id": "ESP",
              "$valor": "España"
            },
            "coord": {
              "x": "-5.45942131",
              "y": "42.45782014"
            }
          }
        }
      ]
    },
    "server": {
      "$valor": "lb.cercalia.com"
    },
    "instance": {
      "$valor": "https://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/json?&cmd=cand&detcand=1&rdc=A-231&munc=ESP441085&km=13&pcode=&ctryc=ESP&key=YOUR_API_KEY

Request

Request example:

https://lb.cercalia.com/services/json?cmd=prox&rqge=ctpcode&ctryc=ESP&pcode=40160&key=YOUR_API_KEY

Where:

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",
              "$valor": "Torrecaballeros"
            },
            "subregion": {
              "id": "ESP40",
              "$valor": "Segovia"
            },
            "region": {
              "id": "ESPCYL",
              "$valor": "Castilla y León"
            },
            "country": {
              "id": "ESP",
              "$valor": "España"
            },
            "coord": {
              "x": "-4.02483875",
              "y": "40.99183593"
            }
          },
          {
            "id": "ESP0052177L",
            "name": "Cabanillas del Monte",
            "municipality": {
              "id": "ESP402038",
              "$valor": "Torrecaballeros"
            },
            "subregion": {
              "id": "ESP40",
              "$valor": "Segovia"
            },
            "region": {
              "id": "ESPCYL",
              "$valor": "Castilla y León"
            },
            "country": {
              "id": "ESP",
              "$valor": "España"
            },
            "coord": {
              "x": "-4.03178273",
              "y": "40.97703001"
            }
          }
        ]
      }
    },
    "server": {
      "$valor": "lb.cercalia.com"
    },
    "instance": {
      "$valor": "http://cercalia-lbs-both-lines"
    }
  }
}

Where:

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

Last modified April 24, 2025: fix(geocoding): apply corrections to the page text (d84c402)

Geocoding

Web services

Address geocoding service

Request

Response

Road milestone geocoding service (avaliable for Spain, France, Portugal and Andorra)

Request

Response

List of cities related to a postal Code

Request

Response