This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Reverse Geocoding API

Comprehensive documentation for integrating Cercalia’s Reverse 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

Reverse geocoding

Request

Request example in JSON (lat,long 37.777041,-3.785477):

https://lb.cercalia.com/services/json?cmd=prox&mocs=gdd&mo=37.777041,-3.785477&rqge=adr&key=YOUR_API_KEY

For grouping several coordinates in a single request, use &molist= parameter:

https://lb.cercalia.com/services/xml?cmd=prox&mocs=gdd&molist=[37.77741,-3.785477],[37.87704,-3.78577]&rqge=adr&key=YOUR_API_KEY

* Maximum number of coordinates in a single request: 100.

Where:

Code	Description
`mocs`	GDD coordinate system. “gdd” = geographical system (latitude, longitude)
`mo`	Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (Mercator, UTM, etc)
`rqge`	Level of detail

rqge values:

Value	Description
`cadr`	Address (only streets/roads with name, not road number)
`adr`	Address/road (including road number) and milestone if available
`st`	Street (no house number)/road (no milestone)
`ct`	City/locality
`pcode`	Postal code
`mun`	Municipality
`subreg`	Sub-Region
`reg`	Region
`ctry`	Country

Response

Street example:

<cercalia cmd="prox" version="1">
	<proximity center="-421397,4521799" num="1" type="adr">
		<gelist num="1" type="adr">
			<location>
				<municipality id="ESP230503">Jaén</municipality>
				<subregion id="ESP23">Jaén</subregion>
				<region id="ESPAND">Andalucía</region>
				<country id="ESP">España</country>
			</location>
			<ge article="de" dist="42" frc="ep" height="505" id="ESP230503000090371" kmh="50" name="Avenida de Madrid" pos="1" prefix="Avenida" sname="Madrid" zonename="Jaén" zonetype="U">
				<housenumber>66</housenumber>
				<intersection article="de" dist="51" id="ESP230503000090318" name="Calle de Isaac Albéniz" prefix="Calle" sname="Isaac Albéniz">
					<coord x="-421403" y="4521748"/>
				</intersection>
				<postalcode country_id="ESP" id="23008"/>
				<city id="ESP17240006020330">Jaén</city>
				<municipality id="ESP230503">Jaén</municipality>
				<subregion id="ESP23">Jaén</subregion>
				<region id="ESPAND">Andalucía</region>
				<country id="ESP">España</country>
				<coord x="-421378" y="4521837"/>
			</ge>
		</gelist>
	</proximity>
</cercalia>

Where:

Code	Description
`dist`	Distance in meters between coordinate and street
`kmh`	Theoretical maximum speed in the road segment (source: TomTom). In Anglo-Saxon countries, this value is in miles per hour (not km/h)
`name`	Street name (prefix + article + name)
`prefix`	Street name prefix
`sname`	Street name
`article`	Article
`housenumber`	House number (if available)
`height`	Road point height, in meters
`zonetype`	Zone type: urban (“U”) or industrial (“I”)
`zonename`	Zone name (city or industrial area)
`district`	District name (infra-municipal division, only available in some countries)
`municipality`	Municipality (official ID and name)
`subregion`	Subregion (official ID and name)
`region`	Region (official ID and name)
`country`	Country (official ID and name)

In addition, is avialiable the node corresponding to the closest road junction

Road example:

<cercalia cmd="prox" version="1">
	<proximity center="-404736,4937053" num="1" type="adr">
		<gelist num="1" type="adr">
			<location>
				<municipality id="ESP281296">San Agustín del Guadalix</municipality>
				<subregion id="ESP28">Madrid</subregion>
				<region id="ESPMAD">Comunidad de Madrid</region>
				<country id="ESP">España</country>
			</location>
			<ge dist="0" frc="na2" height="666" kmh="90" name="M-104" pos="1">
				<km>2</km>
				<postalcode country_id="ESP" id="28750"/>
				<city dist="2225" id="ESP17240002420619">San Agustín del Guadalix</city>
				<municipality id="ESP281296">San Agustín del Guadalix</municipality>
				<subregion id="ESP28">Madrid</subregion>
				<region id="ESPMAD">Comunidad de Madrid</region>
				<country id="ESP">España</country>
				<coord x="-404736" y="4937053"/>
			</ge>
		</gelist>
	</proximity>
</cercalia>

Where the parameters are the same as in the case of street, with the exception of the records that refer to the road.

Code	Description
`Name`	Road number/code
`km`	Milestone (available in France, Spain, and Portugal)
`direction`	Road direction (only available for highways): A (increasing milestone) - D (decreasing milestone)
`frc`	Road type

Frc values:

frc	Road type
`ap`	Toll road - highway
`av`	Dual carriageway
`na1`	First level road
`a2`	Second level road
`pl`	Third level road
`ep`	Main street
`cl`	Secondary street
`pt`	Pedestrian street

Get the localities / regions that intersect a polygon

Request

Example:

https://lb.cercalia.com/services/json?cmd=prox&rqge=mun&cs=4326&wkt=POLYGON((2.149028778076172%2041.39586980544921,2.146625518798828%2041.41930231731321,2.1816444396972656%2041.41981722266227,2.1813011169433594%2041.398187683195694,2.149028778076172%2041.39586980544921))&key=YOUR_API_KEY

Where:

Code	Description
`cs`	4326 Polygon coordinate system. 4326 = geographical coordinates (LonLat)
`wkt`	Polygon, in WKT format
`rqge`	Detail level

rqge values:

rqge	desc
`ct`	Locality
`mun`	Municipality
`subreg`	Subregion
`reg`	Region

Response

{
  "cercalia": {
    "cmd": "prox",
    "version": "1",
    "proximity": {
      "buffer": "0.0",
      "cs": "4326",
      "tolerance": "0.0",
      "type": "mun",
      "wkt": "POLYGON((2.149028778076172 41.39586980544921,2.146625518798828 41.41930231731321,2.1816444396972656 41.41981722266227,2.1813011169433594 41.398187683195694,2.149028778076172 41.39586980544921))",
      "gelist": {
        "num": "1",
        "type": "mun",
        "ge": [
          {
            "id": "ESP080193",
            "name": "Barcelona",
            "pos": "1",
            "subregion": {
              "id": "ESP08",
              "$valor": "Barcelona"
            },
            "region": {
              "id": "ESPCAT",
              "$valor": "Catalunya"
            },
            "country": {
              "id": "ESP",
              "$valor": "España"
            },
            "coord": {
              "x": "2.1699165",
              "y": "41.38791358"
            }
          }
        ]
      }
    },
    "server": {
      "$valor": "ws.cercalia.com"
    },
    "instance": {
      "$valor": "http://cercalia-lbs-both-lines"
    }
  }
}

Get the censal section from a coordinate (only avaliable in Spain)

Request

Example:

https://lb.cercalia.com/services/json?cmd=prox&mo=40.3446890,-3.653151816&mocs=gdd&rqpoicats=d00seccen&key=YOUR_API_KEY

Where:

Code	Description
`mo`	Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (Mercator, UTM, etc)

Response

Format:

{
  "cercalia": {
    "cmd": "prox",
    "version": "1",
    "proximity": {
      "center": "-3.65315182,40.34468901",
      "num": "1",
      "type": "poi",
      "poilist": {
        "num": "1",
        "poi": [
          {
            "category_id": "D00SECCEN",
            "dist": "0",
            "geometry": "Z",
            "id": "D00SECCEN#DC00SC2807918002",
            "pos": "1",
            "subcategory_id": "-1",
            "name": {
              "$valor": "2807918002"
            },
            "info": {
              "$valor": "2807918002"
            },
            "ge": {
              "street": {
                "id": "UNKNOWN"
              },
              "city": {
                "id": "UNKNOWN",
                "$valor": "Madrid"
              },
              "municipality": {
                "id": "ESP280796",
                "$valor": "Madrid"
              },
              "subregion": {
                "id": "ESP28",
                "$valor": "Madrid"
              },
              "region": {
                "id": "ESPMAD",
                "$valor": "Comunidad de Madrid"
              },
              "country": {
                "id": "ESP",
                "$valor": "España"
              }
            },
            "coord": {
              "x": "-3.65200197",
              "y": "40.35683327"
            }
          }
        ]
      }
    },
    "server": {
      "$valor": "ws.cercalia.com"
    },
    "instance": {
      "$valor": "http://cercalia-lbs-both-lines"
    }
  }
}

Where:

Code	Description
`name`	Censal section ID
`info`	Censal section ID

Get the SIGPAC parcel from a coordinate (only avaliable in Spain)

Request

Example:

https://lb.cercalia.com/services/json?cmd=prox&mo=41.426362180,2.038241447&mocs=gdd&rqpoicats=d00sigpac&key=YOUR_API_KEY

Where:

Code	Description
`mo`	Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (Mercator, UTM, etc).

Response

Format:

{
  "cercalia": {
    "cmd": "prox",
    "version": "1",
    "proximity": {
      "center": "2.03824145,41.42636218",
      "num": "1",
      "type": "poi",
      "poilist": {
        "num": "1",
        "poi": [
          {
            "category_id": "D00SIGPAC",
            "dist": "0",
            "geometry": "Z",
            "id": "D00SIGPAC#D00_08122_0_0_4_9000_1",
            "pos": "1",
            "subcategory_id": "-1",
            "name": {
              "$valor": "08122:0:0:4:9000:1"
            },
            "info": {
              "$valor": "08122|ZU|19.254569471||0"
            },
            "ge": {
              "street": {
                "id": "UNKNOWN"
              },
              "city": {
                "id": "UNKNOWN",
                "$valor": "Molins de Rei"
              },
              "municipality": {
                "id": "ESP081234",
                "$valor": "Molins de Rei"
              },
              "subregion": {
                "id": "ESP08",
                "$valor": "Barcelona"
              },
              "region": {
                "id": "ESPCAT",
                "$valor": "Catalunya"
              },
              "country": {
                "id": "ESP",
                "$valor": "España"
              }
            },
            "coord": {
              "x": "2.0397596",
              "y": "41.42864741"
            }
          }
        ]
      }
    },
    "server": {
      "$valor": "ws.cercalia.com"
    },
    "instance": {
      "$valor": "http://cercalia-lbs-both-lines"
    }
  }
}

Where:

Code	Description
`name`	SIGPAC parcel ID
`info`	SIGPAC parcel info, with this format:
	`field1\|field2\|field3\|field4\|field5`
	`field1` = municipality ID (INE)
	`field2` = parcel usage
	`field3` = parcel extension (Ha)
	`field4` = vulnerable area type
	`field5` = vulnerable area code

Get the Time Zone from a coordinate

Request

Example:

https://lb.cercalia.com/services/json?cmd=prox&mocs=gdd&mo=52.252025183,20.995254141&rqge=timezone&clientid=0123456789&datetime=2019-09-27T14:30:12Z&key=YOUR_API_KEY

Where:

Code	Description
`mo`	Y,X in case of geographical coordinate system (ex: London = 51.50015,-0.12624), X,Y for other coordinate systems (Mercator, UTM, etc).
`datetime`	Day and time to check (optional). If used, returns the local time in the region where the coordinates are located.

Response

{
  "cercalia": {
    "cmd": "prox",
    "version": "1",
    "proximity": {
      "center": "20.99525414,52.25202518",
      "num": "1",
      "type": "timezone",
      "gelist": {
        "num": "1",
        "type": "timezone",
        "ge": [
          {
            "daylightsavingtime": "3600000",
            "dist": "0",
            "id": "Europe/Warsaw",
            "localdatetime": "2019-09-27T16:30:12+02:00",
            "name": "Central European Time",
            "pos": "1",
            "utcdatetime": "2019-09-27T14:30:12Z",
            "utctimeoffset": "3600000"
          }
        ]
      }
    },
    "server": {
      "$valor": "ws.cercalia.com"
    },
    "instance": {
      "$valor": "http://cercalia-lbs-both-lines"
    }
  }
}

Where:

Code	Description
`id`	Time zone ID
`name`	Time zone name
`localdatetime`	Local time
`utcdatetime`	UTC time
`utctimeoffset`	Offset between local time and UTC time
`daylightsavingtime`	Returns if this date is in summer or winter time