GeoDojo: Locate API

Introduction
Reference
Examples

The Locate API uses a variety of publicly available geographic datasets and provides:

Suggestion of landmarks close to locations
Conversion of locations to grid references
Identification of regions containing locations
Identification of nearest regions to locations

An input location can be either a grid reference or coordinates or the name of a location, such as a postcode, road or other landmark. The type of an input location is identified automatically from its format.

Type	Description	Example
`latlng`	WGS84 latitude and longitude in decimal degrees	`51.51315 -0.13885`
`eastnorth`	Ordnance Survey eastings and northings	`529246 181000`
`grid`	Ordnance Survey National Grid reference	`TQ2924681000`
`utm`	Universal Transverse Mercator coordinates	`30 N 698525 5710773`
`geohash`	Geohash identifier	`gcpvhcdvue`
`postcode`	UK postcode	`W1F 7DA`
`place`	UK road or place name	`Carnaby Street, London`

Some input names are unique, such as postcodes, but others, such as roads, can be differentiated by including the name or part of the name of the nearest place. For example, Carnaby Street Lond matches Carnaby Street in London. Endpoints which expect a unique location as input will choose the alphabetically first match including the place.

Containing element queries of a point for geographic datasets from a number of organisations are supported. These datasets are based on polygons.

Nearest element to a point queries for geographic datasets from a number of organisations are supported. These datasets can be based on points, polylines or polygons. The nearest location on an element of the dataset and its distance is reported. The points match and the distance is zero for locations inside polygons, locations on polylines or locations which coincide with a point.

The API supports both GET and POST requests. The latter can have JSON or URL-encoded bodies and the format should be specified via the Content-Type header. CORS is supported, allowing JavaScript requests across domains.

Use of the API does not require registration or authentication. This is subject to fair-use and there exists a limit of 60 requests per minute to any of the endpoints. If a number of locations need to be processed then these should be passed as an array with a single request, instead of using many requests for individual locations.

Headers are added to the response allowing a client to track their usage of the API:

Header	Description
`X-GeoDojo-Ratelimit`	Maximum number of requests per minute
`X-GeoDojo-Ratelimit-Used`	Current requests per minute used
`X-GeoDojo-Ratelimit-Remaining`	Current requests per minute remaining

The API is free to use and this site does not display adverts. If you find the API useful and would like to contribute to server costs or just buy the developer a coffee then you can visit buymeacoffee.com/geodojo.

Please contact hello@geodojo.net with any problems or feedback.

Contains OS data © Crown copyright and database rights 2024.
Source: Office for National Statistics licensed under the Open Government Licence v.3.0.
Contains data © OpenStreetMap contributors.
Contains public sector information licensed under the Open Government Licence v3.0.
Contains data © Historic England 2023.

Find Locations

This endpoint will convert a location into suggestions for grid references. The output includes the name, type and nearest place of the matched locations.

curl --request GET --url 'https://api.geodojo.net/locate/find?q=Carnaby+Street&max=10'

curl --request POST --url 'https://api.geodojo.net/locate/find' --header 'Content-Type: application/json' --data '{"q":"Carnaby Street","max":10}'

Endpoint URL

https://api.geodojo.net/locate/find

Parameters

Parameter	Required/Optional	Description	Example
`q`	required	Location as string or locations as array of strings	`q=Carnaby+Street`
`type`	optional	Output location type. Defaults to `latlng`.	`type=grid`
`max`	optional	Maximum number of output locations. Defaults to `1`.	`max=10`

Example Requests

GET /locate/find?q=Carnaby+Street&max=10 HTTP/1.1
Host: api.geodojo.net

POST /locate/find HTTP/1.1
Host: api.geodojo.net
Content-Type: application/json
Content-Length: 31

{"q":"Carnaby Street","max":10}

Example Response

{
  "location":"Carnaby Street",
  "result":[
    {
      "location":"Carnaby Street",
      "type":"named-road-centre",
      "place":"Bilston (Wolverhampton)",
      "latlng":"52.569296 -2.077253"
    },
    {
      "location":"Carnaby Street",
      "type":"named-road-centre",
      "place":"London",
      "latlng":"51.51315 -0.138845"
    },
    {
      "location":"Carnaby Street",
      "type":"named-road-centre",
      "place":"Manchester",
      "latlng":"53.514455 -2.201027"
    }
  ]
}

Get Grid References

This endpoint will convert input locations to grid references. The result includes data for each combination of location and grid reference type.

curl --request GET --url 'https://api.geodojo.net/locate/grid?q[]=WC2N+5DU&q[]=52.5692+-2.0772&type[]=grid&type[]=geohash&precision=100'

curl --request POST --url 'https://api.geodojo.net/locate/grid' --header 'Content-Type: application/json' --data '{"q":["WC2N 5DU","52.5692 -2.0772"],"type":["grid","geohash"],"precision":100}'

Endpoint URL

https://api.geodojo.net/locate/grid

Parameters

Parameter	Required/Optional	Description	Example
`q`	required	Location as string or locations as array of strings	`q[]=WC2N+5DU&q[]=52.5692+-2.0772`
`type`	optional	Output grid reference types as string or array of strings. Suported types include `eastnorth`, `geohash`, `grid`, `latlng` and `utm`. Defaults to `latlng`.	`type[]=grid&type[]=geohash`
`precision`	optional	Precision of output grid references in metres. Defaults to `1`.	`precision=100`

Example Requests

GET /locate/grid?q[]=WC2N+5DU&q[]=52.5692+-2.0772&type[]=grid&type[]=geohash&precision=100 HTTP/1.1
Host: api.geodojo.net

POST /locate/grid HTTP/1.1
Host: api.geodojo.net
Content-Type: application/json
Content-Length: 78

{"q":["WC2N 5DU","52.5692 -2.0772"],"type":["grid","geohash"],"precision":100}

Example Response

[
  {
    "location":"WC2N 5DU",
    "result":{
      "grid":"TQ299803",
      "geohash":"gcpvj0d"
    }
  },
  {
    "location":"52.5692 -2.0772",
    "result":{
      "grid":"SO948968",
      "geohash":"gcqe09z"
    }
  }
]

Get Supported Grid Reference Types

This endpoint will return the supported types of grid references.

curl --request GET --url 'https://api.geodojo.net/locate/grid/types'

Endpoint URL

https://api.geodojo.net/locate/grid/types

Example Request

GET /locate/grid/types HTTP/1.1
Host: api.geodojo.net

Example Response

{
  "grid":[
    "eastnorth",
    "geohash",
    "grid",
    "latlng",
    "utm"
  ]
}

Get Containing Regions

This endpoint will convert input locations to containing regions. The result includes data for each combination of location and region type.

curl --request GET --url 'https://api.geodojo.net/locate/region?q[]=529936+180439&q[]=TQ29248100&type[]=ward&type[]=major-town-city&type[]=ceremonial-county'

curl --request POST --url 'https://api.geodojo.net/locate/region' --header 'Content-Type: application/json' --data '{"q":["529936 180439","TQ29248100"],"type":["ward","major-town-city","ceremonial-county"]}'

Endpoint URL

https://api.geodojo.net/locate/region

Parameters

Parameter	Required/Optional	Description	Example
`q`	required	Location as string or locations as array of strings	`q[]=529936+180439&q[]=TQ29248100`
`type`	required	Output location types as string or array of strings.	`type[]=ward&type[]=major-town-city&type[]=ceremonial-county`

Example Requests

GET /locate/region?q[]=529936+180439&q[]=TQ29248100&type[]=ward&type[]=major-town-city&type[]=ceremonial-county HTTP/1.1
Host: api.geodojo.net

POST /locate/region HTTP/1.1
Host: api.geodojo.net
Content-Type: application/json
Content-Length: 90

{"q":["529936 180439","TQ29248100"],"type":["ward","major-town-city","ceremonial-county"]}

Example Response

[
  {
    "location":"529936 180439",
    "result":{
      "ward":"St James's",
      "major-town-city":"London",
      "ceremonial-county":"Greater London"
    }
  },
  {
    "location":"TQ29248100",
    "result":{
      "ward":"West End",
      "major-town-city":"London",
      "ceremonial-county":"Greater London"
    }
  }
]

Get Supported Containing Region Types

This endpoint will return the supported types of containing regions. The region names are divided into groups in the output.

curl --request GET --url 'https://api.geodojo.net/locate/region/types'

Endpoint URL

https://api.geodojo.net/locate/region/types

Example Request

GET /locate/region/types HTTP/1.1
Host: api.geodojo.net

Example Response

{
  "administrative":[
    "civil-parish-or-community",
    "county-unitary-authority",
    "district-ward",
    "district",
    "greater-london-authority",
    "local-authority-district",
    "london-borough-ward",
    "london-borough",
    "metropolitan-county",
    "metropolitan-district-ward",
    "metropolitan-district",
    "non-civil-parish-or-community",
    "non-civil-parish",
    "non-metropolitan-county-electoral-division",
    "non-metropolitan-county",
    "parish",
    "polling-district",
    "region",
    "unitary-authority-electoral-division",
    "unitary-authority-ward",
    "unitary-authority",
    "ward"
  ],
  "aero":[
    "airfield",
    "airport",
    "helicopter-station",
    "heliport"
  ],
  "building":[
    "functional-site",
    "glasshouse",
    "important-building"
  ],
  "bus":[
    "bus-station-coach-station",
    "bus-station",
    "coach-station"
  ],
  "coast":[
    "port-consisting-of-docks-and-nautical-berthing"
  ],
  "constituency":[
    "greater-london-authority-assembly-constituency",
    "westminster-constituency",
    "westminster-parliamentary-constituency"
  ],
  "country":[
    "country"
  ],
  "county":[
    "ceremonial-county",
    "county",
    "historic-county"
  ],
  "culture":[
    "art-gallery",
    "library",
    "museum"
  ],
  "education":[
    "further-education-higher-or-university-education",
    "further-education-non-state-primary-education-non-state-secondary-education",
    "further-education-non-state-secondary-education",
    "further-education-primary-education-secondary-education",
    "further-education-secondary-education",
    "further-education",
    "higher-or-university-education",
    "non-state-primary-education-non-state-secondary-education",
    "non-state-primary-education",
    "non-state-secondary-education",
    "primary-education-secondary-education",
    "primary-education",
    "secondary-education",
    "special-needs-education"
  ],
  "emergency":[
    "fire-rescue-authority",
    "fire-station",
    "police-force-area",
    "police-station"
  ],
  "england":[
    "english-region"
  ],
  "europe":[
    "european-electoral-region",
    "historic-european-region"
  ],
  "government":[
    "combined-authority",
    "local-planning-authority"
  ],
  "greenspace":[
    "allotments-or-community-growing-spaces",
    "aonb",
    "cemetery",
    "country-park",
    "greenspace-site",
    "local-nature-reserve",
    "national-nature-reserve",
    "national-park",
    "park-garden",
    "public-park-or-garden"
  ],
  "health":[
    "cancer-alliance",
    "clinical-commissioning-group",
    "covid-infection-survey",
    "integrated-care-board",
    "public-health-england-centre",
    "public-health-england-region",
    "strategic-clinical-network",
    "sub-integrated-care-board-location"
  ],
  "heritage":[
    "ancient-woodland",
    "battlefield",
    "national-character-area",
    "protected-wrecks",
    "scheduled-monument",
    "world-heritage-site"
  ],
  "legal":[
    "combined-authority"
  ],
  "leisure":[
    "play-space",
    "tourist-information"
  ],
  "medical":[
    "hospice",
    "hospital",
    "medical-care-accommodation",
    "nhs-region-local-office",
    "nhs-region"
  ],
  "partnership":[
    "community-safety-partnership",
    "local-enterprise-partnership",
    "local-resilience-forum",
    "sustainability-transformation-partnership"
  ],
  "place":[
    "built-up-area",
    "major-town-city"
  ],
  "postal":[
    "post-office"
  ],
  "religion":[
    "place-of-worship",
    "religious-grounds"
  ],
  "road":[
    "road-user-services"
  ],
  "science":[
    "sssi",
    "vice-county"
  ],
  "scotland":[
    "scottish-parliament-constituency",
    "scottish-parliament-electoral-region",
    "scottish-parliamentary-constituency",
    "scottish-parliamentary-region"
  ],
  "sport":[
    "bowling-green",
    "golf-course",
    "other-sports-facility",
    "playing-field",
    "sports-and-leisure-centre",
    "tennis-court"
  ],
  "statistics":[
    "itl-1",
    "itl-2",
    "itl-3",
    "lau-1",
    "lau-2",
    "nuts-1",
    "nuts-2",
    "nuts-3",
    "registration-district"
  ],
  "terminal":[
    "passenger-ferry-terminal",
    "vehicular-ferry-terminal"
  ],
  "wales":[
    "dcells-wales",
    "naer-wales",
    "nawer-wales",
    "welsh-community-ward",
    "welsh-local-health-board",
    "welsh-national-assembly-constituency",
    "welsh-parliament-constituency",
    "welsh-parliament-electoral-region"
  ],
  "waterway":[
    "tidal-water"
  ]
}

Get Containing Region Information

This endpoint will return information on the specified containing region datasets.

curl --request GET --url 'https://api.geodojo.net/locate/region/info?type[]=built-up-area&type[]=major-town-city'

curl --request POST --url 'https://api.geodojo.net/locate/region/info' --header 'Content-Type: application/json' --data '{"type":["built-up-area", "major-town-city"]}'

Endpoint URL

https://api.geodojo.net/locate/region/info

Parameters

Parameter	Required/Optional	Description	Example
`type`	optional	Region type as string or region types as array to provide information on. Defaults to `*` for all.	`type[]=built-up-area&type[]=major-town-city`

Example Requests

GET /locate/region/info?type[]=built-up-area&type[]=major-town-city HTTP/1.1
Host: api.geodojo.net

POST /locate/region/info HTTP/1.1
Host: api.geodojo.net
Content-Type: application/json
Content-Length: 45

{"type":["built-up-area", "major-town-city"]}

Example Response

{
  "built-up-area":{
    "organisation":"Ordnance Survey",
    "product":"OS Open Built Up Areas",
    "url":"https:\/\/osdatahub.os.uk\/downloads\/open",
    "file":"OS_Open_Built_Up_Areas\/OS_Open_Built_Up_Areas.csv",
    "date":"2022-11-04"
  },
  "major-town-city":{
    "organisation":"Office for National Statistics",
    "product":"",
    "url":"https:\/\/geoportal.statistics.gov.uk",
    "file":"Major_Towns_and_Cities_(Dec_2015)_Boundaries_V2\/Major_Towns_and_Cities_(Dec_2015)_Boundaries_V2.shp",
    "date":"2022-11-15"
  }
}

Get Nearest Regions

This endpoint will convert input locations to the nearest regions. The output includes the distance to the region and the nearest location of the same type as the input to the region. The output also includes the distance to this nearest location. The result includes data for each combination of location and region type.

curl --request GET --url 'https://api.geodojo.net/locate/nearest?q[]=529936+180439&q[]=TQ29248100&type[]=road&type[]=postcode-centre&type[]=major-town-city'

curl --request POST --url 'https://api.geodojo.net/locate/nearest' --header 'Content-Type: application/json' --data '{"q":["529936 180439","TQ29248100"],"type":["road","postcode-centre","major-town-city"]}'

Endpoint URL

https://api.geodojo.net/locate/nearest

Parameters

Parameter	Required/Optional	Description	Example
`q`	required	Location as string or locations as array of strings	`q[]=529936+180439&q[]=TQ29248100`
`type`	required	Output location types as string or array of strings	`type[]=road&type[]=postcode-centre&type[]=major-town-city`

Example Requests

GET /locate/nearest?q[]=529936+180439&q[]=TQ29248100&type[]=road&type[]=postcode-centre&type[]=major-town-city HTTP/1.1
Host: api.geodojo.net

POST /locate/nearest HTTP/1.1
Host: api.geodojo.net
Content-Type: application/json
Content-Length: 88

{"q":["529936 180439","TQ29248100"],"type":["road","postcode-centre","major-town-city"]}

Example Response

[
  {
    "location":"529936 180439",
    "result":{
      "road":"Trafalgar Square, A4",
      "road-distance":14,
      "road-location":"529949 180443",
      "road-location-distance":14,
      "postcode-centre":"SW1Y 5AY",
      "postcode-centre-distance":8,
      "postcode-centre-location":"529928 180442",
      "postcode-centre-location-distance":8,
      "major-town-city":"London",
      "major-town-city-distance":0,
      "major-town-city-location":"529936 180439",
      "major-town-city-location-distance":0
    }
  },
  {
    "location":"TQ29248100",
    "result":{
      "road":"Carnaby Street",
      "road-distance":4,
      "road-location":"TQ2924381002",
      "road-location-distance":4,
      "postcode-centre":"W1F 7EA",
      "postcode-centre-distance":5,
      "postcode-centre-location":"TQ2923680997",
      "postcode-centre-location-distance":5,
      "major-town-city":"London",
      "major-town-city-distance":0,
      "major-town-city-location":"TQ2924081000",
      "major-town-city-location-distance":0
    }
  }
]

Get Supported Nearest Region Types

This endpoint will return the supported types of nearestregions. The region names are divided into groups in the output.

curl --request GET --url 'https://api.geodojo.net/locate/nearest/types'

Endpoint URL

https://api.geodojo.net/locate/nearest/types

Example Request

GET /locate/nearest/types HTTP/1.1
Host: api.geodojo.net

Example Response

{
  "administrative":[
    "civil-parish-or-community",
    "county-unitary-authority",
    "district",
    "district-ward",
    "greater-london-authority",
    "local-authority-district",
    "london-borough",
    "london-borough-ward",
    "metropolitan-county",
    "metropolitan-district",
    "metropolitan-district-ward",
    "non-civil-parish",
    "non-civil-parish-or-community",
    "non-metropolitan-county",
    "non-metropolitan-county-electoral-division",
    "parish",
    "polling-district",
    "region",
    "unitary-authority",
    "unitary-authority-electoral-division",
    "unitary-authority-ward",
    "ward"
  ],
  "aero":[
    "airfield",
    "airport",
    "helicopter-station",
    "heliport"
  ],
  "building":[
    "functional-site",
    "glasshouse",
    "important-building"
  ],
  "bus":[
    "bus-station",
    "bus-station-coach-station",
    "coach-station"
  ],
  "cartography":[
    "spot-height"
  ],
  "coast":[
    "bay-centre",
    "beach-centre",
    "coastal-headland-centre",
    "coast-path",
    "estuary-centre",
    "group-of-islands-centre",
    "harbour-centre",
    "high-water-mark",
    "island-centre",
    "low-water-mark",
    "other-coastal-landform-centre",
    "port-consisting-of-docks-and-nautical-berthing",
    "sea-centre",
    "tidal-boundary"
  ],
  "constituency":[
    "greater-london-authority-assembly-constituency",
    "westminster-constituency",
    "westminster-parliamentary-constituency"
  ],
  "country":[
    "country"
  ],
  "county":[
    "ceremonial-county",
    "county",
    "historic-county"
  ],
  "culture":[
    "art-gallery",
    "library",
    "museum"
  ],
  "education":[
    "further-education",
    "further-education-higher-or-university-education",
    "further-education-non-state-primary-education-non-state-secondary-education",
    "further-education-non-state-secondary-education",
    "further-education-primary-education-secondary-education",
    "further-education-secondary-education",
    "higher-or-university-education",
    "non-state-primary-education-non-state-secondary-education",
    "non-state-primary-education",
    "non-state-secondary-education",
    "primary-education",
    "primary-education-secondary-education",
    "secondary-education",
    "special-needs-education"
  ],
  "emergency":[
    "fire-rescue-authority",
    "fire-station",
    "police-force-area",
    "police-station"
  ],
  "england":[
    "english-region"
  ],
  "europe":[
    "european-electoral-region",
    "historic-european-region"
  ],
  "government":[
    "combined-authority",
    "local-planning-authority"
  ],
  "greenspace":[
    "aonb",
    "allotments-or-community-growing-spaces",
    "cemetery",
    "country-park",
    "greenspace-access-point",
    "greenspace-site",
    "local-nature-reserve",
    "national-nature-reserve",
    "national-park",
    "park-garden",
    "public-park-or-garden",
    "urban-greenspace",
    "wetland-centre",
    "woodland-or-forest-centre"
  ],
  "health":[
    "cancer-alliance",
    "clinical-commissioning-group",
    "covid-infection-survey",
    "integrated-care-board",
    "public-health-england-centre",
    "public-health-england-region",
    "strategic-clinical-network",
    "sub-integrated-care-board-location"
  ],
  "heritage":[
    "ancient-woodland",
    "battlefield",
    "listed-building",
    "national-character-area",
    "protected-wrecks",
    "scheduled-monument",
    "world-heritage-site"
  ],
  "industry":[
    "chemical-works",
    "oil-refining"
  ],
  "landform":[
    "cirque-or-hollow",
    "cliff-or-slope-centre",
    "hill-or-mountain-centre",
    "hill-or-mountain-ranges-centre",
    "other-landcover-centre",
    "other-landform-centre",
    "valley-centre",
    "waterfall"
  ],
  "legal":[
    "combined-authority"
  ],
  "leisure":[
    "play-space",
    "tourist-information"
  ],
  "medical":[
    "hospice",
    "hospital",
    "medical-care-accommodation",
    "nhs-region",
    "nhs-region-local-office"
  ],
  "partnership":[
    "community-safety-partnership",
    "local-enterprise-partnership",
    "local-resilience-forum",
    "sustainability-transformation-partnership"
  ],
  "place":[
    "built-up-area",
    "city-centre",
    "hamlet-centre",
    "major-town-city",
    "named-place-centre",
    "other-settlement-centre",
    "suburban-area-centre",
    "town-centre",
    "village-centre"
  ],
  "postal":[
    "address-centre",
    "postcode-centre",
    "post-office"
  ],
  "power":[
    "car-charging-point",
    "electricity-distribution",
    "electricity-production",
    "electricity-transmission-line",
    "gas-distribution-or-storage",
    "oil-distribution-or-storage",
    "oil-terminal"
  ],
  "railway":[
    "multi-track",
    "narrow-gauge",
    "railway-centre",
    "railway-station",
    "railway-track",
    "railway-tunnel",
    "single-track",
    "tramway-centre"
  ],
  "religion":[
    "place-of-worship",
    "religious-grounds"
  ],
  "road":[
    "a-road",
    "b-road",
    "local-access-road",
    "local-road",
    "minor-road",
    "motorway",
    "motorway-junction",
    "named-road-centre",
    "numbered-road",
    "restricted-local-access-road",
    "road",
    "road-tunnel",
    "road-user-services",
    "secondary-access-road",
    "section-of-named-road-centre",
    "section-of-numbered-road-centre"
  ],
  "science":[
    "sssi",
    "vice-county"
  ],
  "scotland":[
    "scottish-parliamentary-constituency",
    "scottish-parliamentary-region",
    "scottish-parliament-constituency",
    "scottish-parliament-electoral-region"
  ],
  "sport":[
    "bowling-green",
    "golf-course",
    "other-sports-facility",
    "playing-field",
    "sports-and-leisure-centre",
    "tennis-court"
  ],
  "statistics":[
    "itl-1",
    "itl-2",
    "itl-3",
    "lau-1",
    "lau-2",
    "nuts-1",
    "nuts-2",
    "nuts-3",
    "registration-district"
  ],
  "terminal":[
    "passenger-ferry-terminal",
    "vehicular-ferry-terminal",
    "vehicular-rail-terminal"
  ],
  "wales":[
    "dcells-wales",
    "welsh-local-health-board",
    "naer-wales",
    "welsh-national-assembly-constituency",
    "nawer-wales",
    "welsh-community-ward",
    "welsh-parliament-constituency",
    "welsh-parliament-electoral-region"
  ],
  "waterway":[
    "canal",
    "channel-centre",
    "inland-river",
    "inland-water-centre",
    "lake",
    "tidal-river",
    "tidal-water",
    "watercourse"
  ]
}

Get Nearest Region Information

This endpoint will return information on the specified nearest region datasets.

curl --request GET --url 'https://api.geodojo.net/locate/nearest/info?type[]=built-up-area&type[]=major-town-city'

curl --request POST --url 'https://api.geodojo.net/locate/nearest/info' --header 'Content-Type: application/json' --data '{"type":["built-up-area", "major-town-city"]}'

Endpoint URL

https://api.geodojo.net/locate/nearest/info

Parameters

Parameter	Required/Optional	Description	Example
`type`	optional	Region type as string or region types as array to provide information on. Defaults to `*` for all.	`type[]=built-up-area&type[]=major-town-city`

Example Requests

GET /locate/nearest/info?type[]=built-up-area&type[]=major-town-city HTTP/1.1
Host: api.geodojo.net

POST /locate/nearest/info HTTP/1.1
Host: api.geodojo.net
Content-Type: application/json
Content-Length: 45

{"type":["built-up-area", "major-town-city"]}

Example Response

{
  "built-up-area":{
    "organisation":"Ordnance Survey",
    "product":"OS Open Built Up Areas",
    "url":"https:\/\/osdatahub.os.uk\/downloads\/open",
    "file":"OS_Open_Built_Up_Areas_CSV\/os_open_built_up_areas.csv",
    "date":"2024-03-28"
  },
  "major-town-city":{
    "organisation":"Office for National Statistics",
    "product":"",
    "url":"https:\/\/geoportal.statistics.gov.uk",
    "file":"Major_Towns_and_Cities_(Dec_2015)_Boundaries_V2\/Major_Towns_and_Cities_(Dec_2015)_Boundaries_V2.shp",
    "date":"2022-11-15"
  }
}

JavaScript

Find Locations

A GET request for matching locations:

const params = new URLSearchParams({
  q: 'Carnaby Street',
  max: 10
});
fetch('https://api.geodojo.net/locate/find?' + params)
  .then(response => response.json())
  .then(data => console.log(data));

Get Grid References

A POST request with JSON-encoded body for grid references:

const params = {
  q: ['WC2N 5DU', '52.5692 -2.0772'],
  type: ['grid', 'geohash']
};
fetch('https://api.geodojo.net/locate/grid', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(params)
}).then(response => response.json())
  .then(data => console.log(data));

Get Nearest Regions

A POST request with URL-encoded body for nearest regions:

const params = {
  q: ['529951 180438', 'TQ29248100'],
  type: ['road', 'postcode-centre', 'major-town-city']
};
const urlparams = Object.keys(params).map(key =>
  !Array.isArray(params[key]) ? 
    [key, params[key]].map(encodeURIComponent).join("=") : 
    params[key].map(avalue => 
      [key + "[]", avalue].map(encodeURIComponent).join("=")).join("&")).join("&");
fetch('https://api.geodojo.net/locate/nearest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: urlparams
}).then(response => response.json())
  .then(data => console.log(data));

PHP

Find Locations

A GET request for matching locations:

$params = array(
  'q' => 'Carnaby Street',
  'max' => 10
);
$data = json_decode(file_get_contents('https://api.geodojo.net/locate/find?' . http_build_query($params)), true);
var_dump($data);

Get Grid References

A POST request with JSON-encoded body for grid references:

$params = array(
  'q' => ['WC2N 5DU', '52.5692 -2.0772'],
  'type' => ['grid', 'geohash']
);
$context  = stream_context_create(array(
  'http' => array(
    'method'  => 'POST',
    'header' => 'Content-Type: application/json\r\n',
    'content' => json_encode($params)
  )
));
$data = json_decode(file_get_contents('https://api.geodojo.net/locate/grid', false, $context), true);
var_dump($data);

Get Nearest Regions

A POST request with URL-encoded body for nearest regions:

$params = array(
  'q' => ['529951 180438', 'TQ29248100'],
  'type' => ['road', 'postcode-centre', 'major-town-city']
);
$context  = stream_context_create(array(
  'http' => array(
    'method'  => 'POST',
    'header' => 'Content-Type: application/x-www-form-urlencoded\r\n',
    'content' => http_build_query($params)
  )
));
$data = json_decode(file_get_contents('https://api.geodojo.net/locate/nearest', false, $context), true);
var_dump($data);

Python

Find Locations

A GET request for matching locations:

import requests    
params = {
  'q': 'Carnaby Street',
  'max': 10
}  
data = requests.get('https://api.geodojo.net/locate/find', params=params).json()
print(data)

Get Grid References

A POST request with JSON-encoded body for grid references:

import requests
params = {
  'q': ['WC2N 5DU', '52.5692 -2.0772'],
  'type': ['grid', 'geohash']
}  
data = requests.post('https://api.geodojo.net/locate/grid', json=params).json()
print(data)

Get Nearest Regions

A POST request with JSON-encoded body for nearest regions:

import requests
params = {
  'q': ['529951 180438', 'TQ29248100'],
  'type': ['road', 'postcode-centre', 'major-town-city']
}  
data = requests.post('https://api.geodojo.net/locate/nearest', json=params).json()
print(data)