Getting Started
The Mapsi API provides enterprise-grade mapping and geocoding services at startup-friendly prices. All endpoints return JSON responses and support standard HTTP methods.
Quick Start
Sign up for a free account to get your API key and start with 2,000 requests per day.
Base URL
https://api.mapsi.devAuthentication
All API requests require authentication using your API key in the request headers:
X-API-Key: your_api_key_hereSupported Countries
Most Mapsi APIs require a countries parameter to specify which countries to search within. This improves search accuracy and performance.
⚠️ Important: Country Codes Required
The countries parameter is required for: Geocoding, Reverse Geocoding, Places, and Batch Geocoding APIs.
You must specify between 1 and 4 country codes (ISO 3166-1 alpha-2 format).
The Static Maps API does NOT require country codes.
Country Code Format
# Single country
countries=MC
# Multiple countries (comma-separated, max 4)
countries=MC,FR,ITAvailable Countries
🇲🇨 Monaco
MC🇱🇻 Latvia
LV🇺🇸 United States
US🇨🇦 Canada
CA🇬🇧 United Kingdom
GB🇩🇪 Germany
DE🇫🇷 France
FR🇪🇸 Spain
ES🇮🇹 Italy
IT🇳🇱 Netherlands
NL🇧🇪 Belgium
BE🇨🇭 Switzerland
CH🇦🇹 Austria
AT🇦🇺 Australia
AU🇳🇿 New Zealand
NZ🇮🇪 Ireland
IE🇩🇰 Denmark
DK🇸🇪 Sweden
SEGeocoding API
Convert addresses and place names into geographic coordinates with high accuracy.
Endpoint
GET /api/geocodeParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Address or place name to geocode |
countries | string | Yes | Comma-separated ISO country codes (1-4). Example: MC or MC,FR |
limit | integer | No | Maximum number of results (default: 5, max: 10) |
cURL
curl -X GET "https://api.mapsi.dev/api/geocode?q=4+Avenue+de+la+Madone&countries=MC&limit=5" \
-H "X-API-Key: YOUR_API_KEY"JavaScript
// Geocode an address
const response = await fetch(
'https://api.mapsi.dev/api/geocode?q=4+Avenue+de+la+Madone&countries=MC&limit=5',
{ headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.results[0].geometry);Python
import requests
# Geocode an address
response = requests.get(
"https://api.mapsi.dev/api/geocode",
params={"q": "4 Avenue de la Madone", "countries": "MC", "limit": 5},
headers={"X-API-Key": "YOUR_API_KEY"}
)
data = response.json()
print(data["results"][0]["geometry"])Reverse Geocoding API
Convert geographic coordinates back into human-readable addresses.
Endpoint
GET /api/reverseParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
lat | float | Yes | Latitude coordinate |
lon | float | Yes | Longitude coordinate |
countries | string | Yes | Comma-separated ISO country codes (1-4). Example: MC |
limit | integer | No | Maximum number of results (default: 1) |
cURL
curl -X GET "https://api.mapsi.dev/api/reverse?lat=43.7409&lon=7.4279&countries=MC" \
-H "X-API-Key: YOUR_API_KEY"JavaScript
// Reverse geocode coordinates
const response = await fetch(
'https://api.mapsi.dev/api/reverse?lat=43.7409&lon=7.4279&countries=MC',
{ headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.results[0].formatted_address);Python
import requests
# Reverse geocode coordinates
response = requests.get(
"https://api.mapsi.dev/api/reverse",
params={"lat": 43.7409, "lon": 7.4279, "countries": "MC"},
headers={"X-API-Key": "YOUR_API_KEY"}
)
data = response.json()
print(data["results"][0]["formatted_address"])Places API
Find points of interest, businesses, and landmarks near any location.
Endpoint
GET /api/placesParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Search query (e.g., "coffee", "restaurant") |
lat | float | Yes | Latitude for search center |
lon | float | Yes | Longitude for search center |
countries | string | Yes | Comma-separated ISO country codes (1-4). Example: MC,FR |
limit | integer | No | Maximum number of results (default: 5) |
cURL
curl -X GET "https://api.mapsi.dev/api/places?q=casino&lat=43.7384&lon=7.4246&countries=MC" \
-H "X-API-Key: YOUR_API_KEY"JavaScript
// Search for places nearby
const response = await fetch(
'https://api.mapsi.dev/api/places?q=casino&lat=43.7384&lon=7.4246&countries=MC',
{ headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const places = await response.json();
console.log(places.results);Python
import requests
# Search for places nearby
response = requests.get(
"https://api.mapsi.dev/api/places",
params={"q": "casino", "lat": 43.7384, "lon": 7.4246, "countries": "MC"},
headers={"X-API-Key": "YOUR_API_KEY"}
)
places = response.json()
print(places["results"])Static Maps API
Generate static map images with markers and custom styling.
✅ No Country Code Required
The Static Maps API does not require the countries parameter.
Endpoint
GET /api/static-mapParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
center | string | Yes | Map center as "lat,lon" |
zoom | integer | Yes | Zoom level (1-20) |
size | string | No | Image size as "widthxheight" (default: 600x400) |
cURL
curl -X GET "https://api.mapsi.dev/api/static-map?lat=43.7384&lon=7.4246&zoom=15&width=600&height=400" \
-H "X-API-Key: YOUR_API_KEY" \
--output monaco_map.pngJavaScript
// Get static map image URL
const mapUrl = 'https://api.mapsi.dev/api/static-map?lat=43.7384&lon=7.4246&zoom=15&width=600&height=400';
// Use in HTML
const img = document.createElement('img');
img.src = mapUrl + '&api_key=YOUR_API_KEY';
document.body.appendChild(img);Python
import requests
# Download static map image
response = requests.get(
"https://api.mapsi.dev/api/static-map",
params={"lat": 43.7384, "lon": 7.4246, "zoom": 15, "width": 600, "height": 400},
headers={"X-API-Key": "YOUR_API_KEY"}
)
with open("monaco_map.png", "wb") as f:
f.write(response.content)Batch Geocoding API
Process multiple addresses in a single request for high-throughput applications.
Endpoint
POST /api/batch/geocodeRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
addresses | array | Yes | Array of address strings (max: 100) |
countries | string | Yes | Comma-separated ISO country codes (1-4). Example: MC |
limit | integer | No | Results per address (default: 1) |
cURL
curl -X POST "https://api.mapsi.dev/api/batch/geocode" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"addresses": [
"4 Avenue de la Madone, Monaco",
"Place du Casino, Monte-Carlo"
],
"countries": "MC",
"limit": 1
}'JavaScript
// Batch geocode multiple addresses
const response = await fetch('https://api.mapsi.dev/api/batch/geocode', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
addresses: [
'4 Avenue de la Madone, Monaco',
'Place du Casino, Monte-Carlo'
],
countries: 'MC',
limit: 1
})
});
const results = await response.json();
console.log(results);Python
import requests
# Batch geocode multiple addresses
response = requests.post(
"https://api.mapsi.dev/api/batch/geocode",
json={
"addresses": [
"4 Avenue de la Madone, Monaco",
"Place du Casino, Monte-Carlo"
],
"countries": "MC",
"limit": 1
},
headers={"X-API-Key": "YOUR_API_KEY"}
)
results = response.json()
print(results)Routing API
Calculate optimal routes between points with support for different transportation modes.
Endpoint
GET /api/routingParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
start_lat | float | Yes | Starting point latitude |
start_lon | float | Yes | Starting point longitude |
end_lat | float | Yes | Destination latitude |
end_lon | float | Yes | Destination longitude |
profile | string | No | Transportation mode: "car", "foot", "bicycle" (default: "car") |
cURL
curl -X GET "https://api.mapsi.dev/api/routing?start_lat=43.7384&start_lon=7.4246&end_lat=43.7409&end_lon=7.4279&profile=car" \
-H "X-API-Key: YOUR_API_KEY"JavaScript
// Calculate route between two points
const response = await fetch(
'https://api.mapsi.dev/api/routing?start_lat=43.7384&start_lon=7.4246&end_lat=43.7409&end_lon=7.4279&profile=car',
{ headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const route = await response.json();
console.log('Distance:', route.routes[0].distance, 'meters');Python
import requests
# Calculate route between two points
response = requests.get(
"https://api.mapsi.dev/api/routing",
params={
"start_lat": 43.7384, "start_lon": 7.4246,
"end_lat": 43.7409, "end_lon": 7.4279,
"profile": "car"
},
headers={"X-API-Key": "YOUR_API_KEY"}
)
route = response.json()
print(f"Distance: {route['routes'][0]['distance']} meters")