Geocodificación

Servicios web

Documentación sobre la funcionalidad Geocodificación disponible a través del webservice HTTP-JSON/XML de la plataforma CERCALIA.

La URL base a utilizar es:

* Clave de seguridad. Es la misma KEY que para la API de mapas de Cercalia

Las peticiones HTTP se pueden enviar en GET o POST
Las respuestas son en formato JSON / XML

Petición para normalizar una dirección

Petición para obtener las coordenadas de geolocalización de una dirección, así como el resto de campos de la dirección normalizados.

Petición:


Dirección mediante parámetros separados:

  • cmd= tipo de petición de cercalia
  • adr= dirección (puede incluir el número de portal, piso, puerta, ...)
  • stnum= número de portal (si se dispone de él separado)
  • ctn= nombre de la población
  • pcode= código postal (opcional)
  • rsn= nombre de la región (opcional)
  • ctryc= Código de país, ISO 3 dígitos (ESP) / ctryn= Nombre del país
  • cleanadr= Parámetro para indicar si es necesario limpiar el texto de la dirección. Por ejemplo, del literal correspondiente a piso, puerta, descripción del lugar, ... Valores: 0 (no aplicar), 1 (aplicar).
  • priorityfilter=1  Parámetro que fuerza a priorizar las poblaciones importantes en la búsqueda. Se recomienda su uso

Parámetro adicional opcional: &fullsearch=3 -> Permite realizar una búsqueda más restrictiva de la dirección indicada. En caso de indicar una dirección incluyendo el código postal, comprueba si la dirección encontrada se encuentra en el código postal indicado.  En caso de que sea diferente, se devuelve como respuesta la normalización hasta código postal.

Ejemplo:

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

 

Dirección en un único parámetro:

  • fadr= calle + número + código postal + población
  • ctryc= Código de país, ISO 3 dígitos (ESP) / ctryn= Nombre del país
  • priorityfilter=1  Parámetro que fuerza a priorizar las poblaciones importantes en la búsqueda. Se recomienda su uso
  • mode=1 Parámetro fijo
  • tolstnum= tolerancia respecto al número de portal para considerar el geocoding como óptimo. Se recomienda utilizar este parámetro, y poner un valor de 10 o similar.

Ejemplo:

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

 

Respuesta:

Respuesta de ejemplo de petición generada en XML:

<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>

Donde:

  • id= ID de elemento geográfico normalizado (en este caso calle)
  • name= nombre completo del elemento geográfico normalizado
  • type= tipo de elemento geográfico normalizado (adr = dirección)
    • adr / adr1= dirección exacta
    • adr2= dirección completa, pero con portal aproximado
    • st= calle, sin portal
    • pc= centro de código postal
    • ct= centro de localidad
  • housenumber= número de portal
  • postalcode= código postal de la dirección
  • city= ID y nombre de ciudad
  • municipality= ID y nombre de municipio
  • subregion= ID y nombre de provincia
  • region= ID y nombre de comunidad autónoma
  • country= ID y nombre de país
  • coord x&y= coordenada de la dirección, en formato mercator o geográficas grados decimales (en función de la configuración deseada)

 

En caso de no encontrar ningún candidato, el servicio devolverá el siguiente error:

<cercalia version="1">
   <error id="30006" type="Sistema Cercalia">No se han encontrado candidatos</error/>
</cercalia>

 

Petición para normalizar una carretera y punto kilométrico (España, Francia, Portugal y Andorra)

Petición:

Ejemplo de petición:

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

Donde:

  • cmd= tipo de petición de cercalia
  • rdn= código de carretera
  • km= punto kilométrico
  • direction= sentido ascendente o descendente. Parámetro opcional, solo disponible en autopistas y autovías (vías separadas por una mediana). Posibles valores:
    • Ascendente: A, ASC, I
    • Descendente: D, DESC
    • Ambos (devuelve los dos): BOTH
  • munn= nombre del municipio (opcional)
  • pcode= código postal (opcional)
  • subregn= nombre de la provincia (opcional)
  • ctryc= Código ISO 3 dígitos de país (Ej: España = ESP)
  • detcand=1 indica que queremos obtener los valores normalizados de la dirección en la respuesta XML

Respuesta:

En caso que solo se encuentre un candidato, esta petición genera la respuesta XML:

  <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>

Donde:

  • id= ID de elemento geográfico normalizado (en este caso carretera)
  • name= nombre completo del elemento geográfico normalizado (en esta caso carretera)
  • type= tipo de elemento geográfico normalizado (rd = carretera)
  • postalcode= código postal de la dirección
  • subregion id= ID y nombre de provincia
  • region id= ID y nombre de comunidad autónoma
  • coutry id= ID y nombre de país
  • coord x&y= coordenada de la dirección

En caso que se encuentre más de un candidato, esta petición genera una respuesta más básica de cada candidato (en caso que se superen los 350 candidatos posibles, el sistema pide que se detalle más la búsqueda).

El objetivo es que el usuario seleccione el candidato correcto, y vuelva a lanzar la petición indicando el código de carretera (recogido a partir del ge_id= del candidato seleccionado), utilizando el parámetro &rdc= (road code) en vez de &rdn= (road name). Este paso es necesario, puesto que las coordenadas devueltas en el caso de más de un candidato, són coordenadas por defecto del tramo de carretera, no de la dirección completa indicada.

Ejemplo de petición que devuelve más de un candidato:

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

 

Respuesta XML:

En este caso la nueva petición tiene que arrastrar el valor del parámetro urlparams= del candidato seleccionado.

<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>

En este caso la nueva petición para obtener la geocodificación exacta será (para la carretera A-231):

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

Prueba el Webservice

 
 

Obtener las poblaciones vinculadas a un código postal

Petición:

Ejemplo de petición:

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

Donde:

  • cmd= tipo de petición de cercalia
  • rqge=ctpcode parámetro fijo requerido para obtener la lista de poblaciones vinculadas a un código postal
  • ctryc= Código ISO 3 dígitos de país (Ej: España = ESP)
  • pcode= código postal. Ejemplos: "40160" (ESP), "3415-PT" "3415" (NLD), "2680-344" (PRT)

Respuesta:

Respuesta de ejemplo de petición generada en XML:

  <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>

Donde:

  • id= ID de localidad
  • name= nombre de la localidad
  • municipality= ID y nombre del municipio
  • subregion id= ID y nombre de provincia
  • region id= ID y nombre de comunidad autónoma
  • coutry id= ID y nombre de país
  • coord x&y= coordenada del centro de la población