Geocoding

Web services

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

URL base service:

* API KEY. Same KEY used in maps API js

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:

cmd=cand&detcand=1&priorityfilter=1


Report address with separate parameters:

  • adr= address (including street name and house number)
  • ctn= locality
  • pcode= ZIP 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:

cmd=cand&detcand=1&adr=diagonal 22&ctn=barcelona&ctryc=esp

 

Report address with a single parameter:

  • mode=1 Fixed parameter
  • fadr= Street name + house number + postal code + locality
  • ctryc= country code (ISO 3 characters) / ctryn= country name

Example:

cmd=cand&mode=1&detcand=1&cleanadr=1&fadr=provença 589, 08026 barcelona&ctryc=ESP

 

Response:

Sample in XML format:

<cercalia cmd="cand" version="1">
   <candidates num="1" pos="0" total="1" urlcandidates="" urlcommon="ctn=barcelona&stnum=22&adr=diagonal 22&mode=1&ctryc=esp">
      <candidate desc="Avinguda Diagonal, 22 (Barcelona)" name="Avinguda Diagonal" source="cercalia" urlparams="">
         <urlparams/>
         <ge id="ESP080193000092155" name="Avinguda Diagonal" prefix="Avinguda" sname="Diagonal" type="adr1">
            <name>Avinguda Diagonal, 22</name>
            <housenumber>22</housenumber>
            <postalcode country_id="ESP" id="08019"/>
            <city id="ESP17240008430951">Barcelona</city>
            <district id=""/>
            <municipality id="ESP080193">Barcelona</municipality>
            <subregion id="ESP08">Barcelona</subregion>
            <region id="ESPCAT">Catalunya</region>
            <country id="ESP">España</country>
            <coord x="246587" y="5044811"/>
         </ge>
      </candidate>
      <urlcommon>
         <param name="ctn" value="barcelona"/>
         <param name="stnum" value="22"/>
         <param name="adr" value="diagonal 22"/>
         <param name="mode" value="1"/>
         <param name="ctryc" value="esp"/>
      </urlcommon>
      <urlcandidates/>
   </candidates>
   <server>http://cercalia-tomcat-lbs-instance3:8080</server>
</cercalia>


Where:

  • 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= ZIP code
  • city= locality name
  • municipality= municipality name
  • subregion= region name (level 1)
  • region= region name (level 2)
  • country= country
  • coord x&y= Address coordinates

 

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:

cmd=cand&detcand=1


Request example:

&cmd=cand&detcand=1&rdn=M-45&km=12&munn=&pcode=&subregn=Madrid&ctryc=ESP


Where:

  • rdn= road name
  • km= milestone
  • direction= optional. Road mileston direction (increasing or decreasing). Only available for higways (high capacity road, with a median strip). Values:
    • Increasing: A, ASC, I
    • Decreasing: D, DESC
    • Both: BOTH
  • munn= municipality name (optional)
  • pcode= ZIP code (optional)
  • subregn= region name (optional)
  • ctryc= country code (ISO 3 characters)

Response:

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:

  • name= road name
  • type= geocoding level ("rd"= road)
  • postalcode= ZIP code
  • subregion= region name (level 1)
  • region= region name (level 2)
  • coutry= country
  • coord x&y= milestone coordinades

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:

&cmd=cand&detcand=1&rdn=A231&km=13&pcode=&ctryc=ESP

 

Step one - Response (in XML format):

<cercalia cmd="cand" version="1">
   <candidates num="10" 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">
         <urlparams>
            <param name="km" value="13"/>
            <param name="munc" value="ESP441085"/>
            <param name="rdc" value="A-231"/>
         </urlparams>
         <ge id="A-231" name="A-231" type="rd">
            <name>A-231, Km. 13</name>
            <km>13</km>
            <city id=""/>
            <district id=""/>
            <municipality id="ESP441085">La Fresneda</municipality>
            <subregion id="ESP44">Teruel</subregion>
            <region id="ESPARA">Aragón</region>
            <country id="ESP">España</country>
            <coord x="10080" y="4970486"/>
         </ge>
      </candidate>
      <candidate desc="A-231, pk 13 (Villanueva de las Manzanas)" name="A-231, Km. 13" urlparams="km=13&munc=ESP242186&rdc=A-231">
         <urlparams>
            <param name="km" value="13"/>
            <param name="munc" value="ESP242186"/>
            <param name="rdc" value="A-231"/>
         </urlparams>
         <ge id="A-231" name="A-231" type="rd">
            <name>A-231, Km. 13</name>
            <km>13</km>
            <city id=""/>
            <district id=""/>
            <municipality id="ESP242186">Villanueva de las Manzanas</municipality>
            <subregion id="ESP24">León</subregion>
            <region id="ESPCYL">Castilla y León</region>
            <country id="ESP">España</country>
            <coord x="-607703" y="5200947"/>
         </ge>
      </candidate>
      <urlcommon>
         <param name="pcode" value=""/>
      </urlcommon>
      <urlcandidates>
         <param name="km" value="13"/>
         <param name="rdn" value="A231"/>
         <param name="ctryc" value="ESP"/>
      </urlcandidates>
   </candidates>
   <server>http://cercalia-tomcat-lbs-instance2:8080</server>
</cercalia>


Step two - Second request using the road code (collected from the ge_id = of the selected candidate):  &rdc=A-231

&cmd=cand&detcand=1&rdc=A-231&munc=ESP441085&km=13&pcode=&ctryc=ESP

Test the service

 
 

List of cities related to a ZIP Code

Request:

Request example:

cmd=prox&rqge=ctpcode&ctryc=ESP&pcode=40160

Where:

  • ctryc= country code (ISO 3 characters) / ctryn= country name
  • pcode= ZIP code. Examples: "40160" (ESP), "3415-PT" "3415" (NLD), "2680-344" (PRT)

Response:

Response (in XML format):

  <cercalia cmd="prox" version="1">
    <proximity center="-3.987962906014521,40.98003911865848" num="1" type="ctpcode">
	  <gelist num="2" type="ct">
	    <ge id="ESP17240000177868" name="Cabanillas del Monte"> 
	      <municipality id="ESP402038">Torrecaballeros</municipality> 
	      <subregion id="ESP40">Segovia</subregion> 
	      <region id="ESPCYL">Castilla y León</region> 
	      <country id="ESP">España</country>
		  <coord x="-4.031791708726713" y="40.97703682181006"/> 
	    </ge>
	    <ge id="ESP17240002214824" name="Torrecaballeros"> 
	      <municipality id="ESP402038">Torrecaballeros</municipality> 
	      <subregion id="ESP40">Segovia</subregion> 
	      <region id="ESPCYL">Castilla y León</region> 
	      <country id="ESP">España</country>
		  <coord x="-4.0248477315804685" y="40.99183592644519"/> 
	    </ge>		
      </gelist>

Where:

  • id= City ID
  • name= City name
  • municipality= municipality ID & name
  • subregion id= subregion ID & name
  • region id= region ID & name
  • coutry id= country ID & name
  • coord x&y= X,Y city center