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:

Ejemplo de petición (valores fijos):

&cmd=cand&detcand=1

Dirección mediante parámetros separados:

  • 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

Ejemplo:

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

 

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
  • mode=1 Parámetro fijo
  • 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).
  • 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 2on 2a, 08026 barcelona&ctryc=ESP

 

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)
    • adr1= dirección exacta
    • adr2= dirección completa, pero con portal aproximado
    • adr= dirección completa, pero no se ha podido validar si el portal es el pedido
    • st= calle, sin portal
    • pc= centro de código postal
    • ct= centro de localidad
  • housenumber= número de portal
  • postalcode country_id= 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

Petición:

Ejemplo de petición:

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

Donde:

  • cmd= tipo de petición de cercalia
  • rdn= código de carretera
  • km= punto kilométrico
  • 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 country_id= 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