The basic idea
Geocoding takes an address or place name and returns one or more candidate matches. Each match carries a formatted address, latitude, longitude, a confidence score and details about the kind of feature that matched.
1. Send the address to the geocoding endpoint
Pass the address in the q parameter and, when you know it, a two-letter country code in countries. URL-encode the query if you build the URL yourself.
API
A complete geocoding request
GET /v1/geocode?q=10+Downing+Street%2C+London&countries=GB&limit=5curl -H "X-API-Key: YOUR_MAPSI_API_KEY" \
"https://mapsi.dev/v1/geocode?q=10+Downing+Street%2C+London&countries=GB&limit=5"const response = await fetch(
"https://mapsi.dev/v1/geocode?q=10+Downing+Street%2C+London&countries=GB&limit=5",
{ headers: { "X-API-Key": "YOUR_MAPSI_API_KEY" } }
);
const data = await response.json();
const { lat, lon } = data.results[0].coordinates;import requests
response = requests.get(
"https://mapsi.dev/v1/geocode",
params={"q": "10 Downing Street, London", "countries": "GB", "limit": 5},
headers={"X-API-Key": "YOUR_MAPSI_API_KEY"},
)
data = response.json()
print(data){
"success": true,
"results": [
{
"formatted_address": "10 Downing Street, London, England, United Kingdom",
"house_number": "10",
"street": "Downing Street",
"city": "London",
"region": "Greater London",
"postcode": "SW1A 2AA",
"country_code": "GB",
"country": "United Kingdom",
"coordinates": {
"lat": 51.50333,
"lon": -0.127603
},
"lat": 51.50333,
"lon": -0.127603,
"confidence": 0.9,
"accuracy": "point",
"layer": "address",
"source": "openstreetmap"
}
]
}2. Read latitude and longitude
Each result has a coordinates object (and flat lat and lon fields). Pass them straight to a map library, a spatial database or another API.
const { lat, lon } = data.results[0].coordinates;3. Handle ambiguous or low-confidence matches
Street names repeat across countries and cities, so never assume the first result is right.
Restrict the search with countries, check confidence, accuracy and layer, and ask the user to choose when the top matches are
close. A layer of address with accuracy of point is the most precise kind of match.
Common applications
- Plotting customer addresses on a map
- Building a store locator
- Preparing addresses for spatial analysis
- Calculating delivery distances
- Converting CRM addresses into coordinates