Entry point: /text

Requesting address-like location description for given geographic coordinate.
Getting response formatted as text list.

Request format

HTTP GET request. Any of the following:
GET https://free.geodescription.com/text/lat=LATITUDE/lon=LONGITUDE
GET https://free.geodescription.com/text?lat=LATITUDE&lon=LONGITUDE
GET https://api.geodescription.com/text/lat=LATITUDE/lon=LONGITUDE/key=API-KEY
GET https://api.geodescription.com/text?lat=LATITUDE&lon=LONGITUDE&key=API-KEY
Parameters
lat=LATITUDE
Geographic coordinate latitude as decimal degree. Between -90.0 and 90.0   for example: 51.3034
lon=LONGITUDE
Geographic coordinate longitude as decimal degree. Between -180.0 and 180.0   for example: -0.3063
key=API-KEY
API key associated with purchased API service. Either prepaid or subscribed.
Example request
GET https://free.geodescription.com/text/lat=51.3034/lon=-0.3063

Response format

HTTP response with content-type header as:
content-type: text/plain;charset=utf-8
And with content body formatted as a text list:
locationDetails [, [placeName|boundaryName] ]...
locationDetails  =  [(>100m)] [houseName, ] [houseNumber ] wayDetails | unknownLocation
wayDetails       =  wayName | wayRef | wayName (wayRef)
Text list elements
houseNumber
Address house number if available.
houseName
Address house name if available.
wayName
Name of the street, road, or path.
wayRef
Official reference ID of the road or motorway.
(>100m)
If location is more than 100m away from the request coordinate, "(>100m)" is displayed in front of location details.
placeName
Place name like city, town, or village name. And sub-place name like suburb or neighbourhood name. If both available, sub-place name is listed in front of place name. If place is more than some kilometers away from the request coordinate, "(>15km)" or "(>10km)" or "(>5km)" is displayed in front of place name, depending on whether the place is a city, town or something else.
boundaryName
Name of administrative boundary that encloses the request coordinate such as region or country name. The names of the regions with smaller areas are listed in front of regions with larger areas. The country name is listed the last.
unknownLocation
When a request coordinate is too far away from any land location, "(LAT, LON) (unknown location)" is displayed as a location, where "(LAT, LON)" is the request coordinate. The same happens if request coordinate is outside currently available (enabled) country or territory.
Example responses
Leatherhead Road (A24), Ashtead, Mole Valley, Surrey, England, United Kingdom
(52.312300, 1.737300) (unknown location), England, United Kingdom

Entry point: /textParts

Requesting address-like location description for given geographic coordinate.
Getting response as JSON list.

Request format

HTTP GET request. Any of the following:
GET https://free.geodescription.com/textParts/lat=LATITUDE/lon=LONGITUDE
GET https://free.geodescription.com/textParts?lat=LATITUDE&lon=LONGITUDE
GET https://api.geodescription.com/textParts/lat=LATITUDE/lon=LONGITUDE/key=API-KEY
GET https://api.geodescription.com/textParts?lat=LATITUDE&lon=LONGITUDE&key=API-KEY
Parameters
lat=LATITUDE
Geographic coordinate latitude as decimal degree. Between -90.0 and 90.0   for example: 51.3034
lon=LONGITUDE
Geographic coordinate longitude as decimal degree. Between -180.0 and 180.0   for example: -0.3063
key=API-KEY
API key associated with purchased API service. Either prepaid or subscribed.
Example request
GET https://free.geodescription.com/textParts/lat=51.3034/lon=-0.3063

Response format

HTTP response with content-type header as:
content-type: application/json
And with content body formatted as a JSON list:
"[" LocationObject [ ,PlaceObject | ,BoundaryObject ]... "]"
LocationObject  =  KnownLocationObject | UnknownLocationObject
KnownLocationObject =
  {
    "awayFrom": "...",
    "houseName": "...",
    "houseNumber": "...",
    "wayName": "...",
    "wayRef": "..."
  }
UnknownLocationObject =
  {
    "unknown": true,
    "lat": ##.#####,
    "lon": ###.#####
  }
PlaceObject =
  {
    "awayFrom": "...",
    "place": "...",
    "type": "..."
  }
BoundaryObject =
  {
    "boundary": "...",
    "level": "..."
  }
KnownLocationObject properties
awayFrom
If location is more than 100m away from the request coordinate, "awayFrom": ">100m" is included.
houseName
Address house name. Omitted if not available.
houseNumber
Address house number. Omitted if not available.
wayName
Name of the street, road, or path. Mandatory if wayRef is not available.
wayRef
Official reference ID of the road or motorway. Mandatory if wayName is not available.
UnknownLocationObject properties
When a request coordinate is too far away from any land location, UnknownLocationObject is included. The same happens if request coordinate is outside currently available (enabled) country or territory.
unknown
boolean true.
lat
Request coordinate latitude.
lon
Request coordinate longitude.
PlaceObject properties
awayFrom
If place is more than some kilometers away from the request coordinate, "awayFrom": ">15km" or ">10km" or ">5km" is included. Number of kilometers depends on whether the place is a city, town or something else.
place
Place name like city, town, or village name. And sub-place name like suburb or neighbourhood name. If both available, sub PlaceObject is listed in front of PlaceObject.
type
Possible values: "city", "town", "village", "hamlet", "suburb", "borough", "quarter", "cityBlock", "neighbourhood"
BoundaryObject properties
bounday
Name of administrative boundary that encloses the request coordinate such as region or country name.
level
Boundary administrative level. For country boundary, the level is "top". For region boundary, possible level values range from "-8" to "-1" representing how many levels in hierarchy this boundary is below the top level boundary. BoundaryObject with lower level are listed in front of BoundaryObject with higher level. i.e. level "-3" BoundaryObject is listed in front of level "-2" BoundaryObject. BoundaryObject with top level is listed the last.
Example responses
[
  {
    "wayName": "Leatherhead Road",
    "wayRef": "A24"
  },
  {
    "place": "Ashtead",
    "type": "village"
  },
  {
    "boundary": "Mole Valley",
    "level": "-6"
  },
  {
    "boundary": "Surrey",
    "level": "-4"
  },
  {
    "boundary": "England",
    "level": "-2"
  },
  {
    "boundary": "United Kingdom",
    "level": "top"
  }
]
[
  {
    "unknown": true,
    "lat": 52.3123,
    "lon": 1.7373
  },
  {
    "boundary": "England",
    "level": "-2"
  },
  {
    "boundary": "United Kingdom",
    "level": "top"
  }
]