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

Last modified December 19, 2024: feat: markdown api http all (d8c23c1)