Forward Geocoding API
Send an address, a place name, a postcode or a rough description like "coffee shop near Kings Cross" and get back coordinates, a cleaned up address, its parts, a bounding box and a precision level that tells you how much to trust the point.
Example
$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=221B+Baker+Street,+London&limit=1"Free-form text works. So does a structured query, if you already have the pieces: street=221B Baker Street&city=London&country=gb. Restrict results to one or more countries with countries=gb,ie, bias them toward a point with proximity=lat,lon, or toward a box with bounds.
{
"status": "ok",
"query": "221B Baker Street, London",
"results": [
{
"formatted": "Baker Street, London NW1, United Kingdom",
"lat": 51.522187,
"lon": -0.157338,
"type": "street",
"precision": "street",
"confidence": 0.6,
"place_id": "iA4lb4swQnYoKtB3oye9EOydFFAWdFsuow",
"components": {
"road": "Baker Street",
"city": "London",
"state": "Greater London",
"postcode": "NW1",
"country": "United Kingdom",
"country_code": "gb"
},
"bounds": { "north": 51.525187, "south": 51.519189, "east": -0.154338, "west": -0.160338 },
"codes": {
"plus_code": "9C3XGRCV+V3",
"geohash": "gcpvh7m6mzb2",
"mgrs": "30UXC9720211727",
"maidenhead": "IO91wm15",
"dms": {
"lat": "51° 31' 19.9\" N",
"lon": "0° 9' 26.4\" W"
},
"mapcode": "GBR 88.VH",
"mapcode_international": "VHGQS.7Z5Z"
}
}
]
}What you get back
| Field | Meaning |
|---|---|
formatted | The full address, written the way that country writes addresses. |
lat, lon | Decimal degrees, WGS 84. Up to six decimals. |
type | What was matched: address, street, postcode, city, region, country or poi. |
precision | house, street, postcode, city, region or country. See coverage. |
confidence | 0 to 1. How sure we are this is the place you meant, given the query. Independent of precision: a city query can be matched with confidence 1 at precision city. |
components | The address broken into parts, with the same key names in every country. Only the parts that exist are present. |
place_id | An opaque identifier for the place. The same place always has the same one; send it back as place_id to look the place up again. |
bounds | A bounding box for the matched feature: the building, the street, the postcode area or the city. |
timezone, elevation_m, country_info, codes, sun, regions and more | Off by default, each behind its own flag: the time zone (timezone=1), ground height (elevation=1), country facts, sun times, the areas the point lies in and more, or all of them with annotations=1. A house, street or point of interest always carries its location codes, and a city, region or country its population. See annotations. |
Where it is used
Cleaning customer addresses
Geocode on signup and store formatted and components alongside what the customer typed. Reject anything below precision: street and ask them to check.
Putting records on a map
Batch through a CSV of store or property addresses at 50 a second and plot them. The bounds field gives you a sensible zoom for each.
Search by place
Turn "flats in Hackney" into a bounding box and query your own database with it. type tells you whether the user typed a city, a street or a building.
Accuracy
House-level results depend on address data existing for that country, and it does not exist everywhere. The coverage page lists the best level we reach in each of 252 countries and territories. Where we cannot match a house number we fall back to the street, then the postcode, then the locality, and the precision field says which. We never return a country centroid labelled as an address.
Price and limits
One call is one request, however many results it returns (up to 10 with limit). Every account has 2,500 free requests a day, shared by all of its keys; past that, €0.0001 each from prepaid credit, or nothing on an Unlimited key (€50 a month). Pricing details.
Migrating from another provider? The Google, Bing, HERE, Mapbox and other drop-in hosts answer forward geocoding requests in those providers' formats.