API Documentation

Getting Started

Mapsi provides enterprise-grade geocoding and mapping APIs with global coverage. Our APIs support worldwide address search without requiring country codes.

🌍 Global Coverage

Search addresses worldwide. Country codes are optional - use them to improve accuracy when you know the target region.

Base URL

https://mapsi.dev

Key Features

Global Search - No country code required
High Accuracy - 90%+ accuracy in major markets
Fast Response - Sub-100ms average response time
Multiple Languages - Response language support

Authentication

All API requests require authentication using your API key in the request headers:

X-API-Key: your_api_key_here

Get your API key from the Dashboard.

Rate Limits

Rate limits vary by subscription tier:

Plan	Rate Limit	Daily Limit	Batch Size
Growth	15 req/sec	35,000/day	5,000 records
Business	25 req/sec	140,000/day	30,000 records

Geocoding API

Convert addresses and place names into geographic coordinates with high accuracy.

Endpoint

GET /v1/geocode

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Address or place name to geocode
`countries`	string	No	Optional. Comma-separated ISO country codes (max 4). Example: `FR` or `FR,DE,IT`
`limit`	integer	No	Maximum number of results (default: 5, max: 25)
`lang`	string	No	Response language code (default: en). Example: `de`, `fr`, `es`

cURL

curl -X GET "https://mapsi.dev/v1/geocode?q=Eiffel+Tower+Paris&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

# With optional country filter:
curl -X GET "https://mapsi.dev/v1/geocode?q=Eiffel+Tower+Paris&countries=FR&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

// Geocode an address (global search)
const response = await fetch(
  'https://mapsi.dev/v1/geocode?q=Eiffel+Tower+Paris&limit=5',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.results[0].geometry);

// With optional country filter
const responseFiltered = await fetch(
  'https://mapsi.dev/v1/geocode?q=Eiffel+Tower+Paris&countries=FR&limit=5',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);

Python

import requests

# Geocode an address (global search - no country filter)
response = requests.get(
    "https://mapsi.dev/v1/geocode",
    params={"q": "Eiffel Tower, Paris", "limit": 5},
    headers={"X-API-Key": "YOUR_API_KEY"}
)
data = response.json()
print(data["results"][0]["geometry"])

# With optional country filter
response = requests.get(
    "https://mapsi.dev/v1/geocode",
    params={"q": "Eiffel Tower, Paris", "countries": "FR", "limit": 5},
    headers={"X-API-Key": "YOUR_API_KEY"}
)

Autocomplete API

Get real-time address suggestions as users type. Perfect for address input forms.

Endpoint

GET /v1/autocomplete

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Partial address text to autocomplete
`countries`	string	No	Optional. Comma-separated ISO country codes (max 4)
`limit`	integer	No	Maximum number of suggestions (default: 5, max: 10)
`lang`	string	No	Response language code (default: en)

cURL

curl -X GET "https://mapsi.dev/v1/autocomplete?q=main+str&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

# With optional country filter:
curl -X GET "https://mapsi.dev/v1/autocomplete?q=main+str&countries=US&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

// Address autocomplete (global search)
const response = await fetch(
  'https://mapsi.dev/v1/autocomplete?q=main+str&limit=5',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
const suggestions = await response.json();
console.log(suggestions.results);

Python

import requests

# Address autocomplete
response = requests.get(
    "https://mapsi.dev/v1/autocomplete",
    params={"q": "main str", "limit": 5},
    headers={"X-API-Key": "YOUR_API_KEY"}
)
suggestions = response.json()
print(suggestions["results"])

Reverse Geocoding API

Convert geographic coordinates back into human-readable addresses.

Endpoint

GET /v1/reverse

Parameters

Parameter	Type	Required	Description
`lat`	float	Yes	Latitude coordinate
`lon`	float	Yes	Longitude coordinate
`countries`	string	No	Optional. Comma-separated ISO country codes (max 4)
`limit`	integer	No	Maximum number of results (default: 1, max: 10)

cURL

curl -X GET "https://mapsi.dev/v1/reverse?lat=48.8584&lon=2.2945&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

# With optional country filter:
curl -X GET "https://mapsi.dev/v1/reverse?lat=48.8584&lon=2.2945&countries=FR" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

// Reverse geocode coordinates
const response = await fetch(
  'https://mapsi.dev/v1/reverse?lat=48.8584&lon=2.2945',
  { 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://mapsi.dev/v1/reverse",
    params={"lat": 48.8584, "lon": 2.2945},
    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 /v1/places

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (e.g., "coffee", "restaurant")
`lat`	float	No	Latitude for search center (improves relevance)
`lon`	float	No	Longitude for search center (improves relevance)
`countries`	string	No	Optional. Comma-separated ISO country codes (max 4)
`limit`	integer	No	Maximum number of results (default: 10)

cURL

curl -X GET "https://mapsi.dev/v1/places?q=restaurant&lat=48.8584&lon=2.2945&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

# With optional country filter:
curl -X GET "https://mapsi.dev/v1/places?q=restaurant&lat=48.8584&lon=2.2945&countries=FR" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

// Search for places nearby
const response = await fetch(
  'https://mapsi.dev/v1/places?q=restaurant&lat=48.8584&lon=2.2945',
  { 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://mapsi.dev/v1/places",
    params={"q": "restaurant", "lat": 48.8584, "lon": 2.2945},
    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 /v1/static-map

Parameters

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://mapsi.dev/v1/static-map?lat=48.8584&lon=2.2945&zoom=15&width=600&height=400" \
  -H "X-API-Key: YOUR_API_KEY" \
  --output map.png

JavaScript

// Get static map image URL
const mapUrl = 'https://mapsi.dev/v1/static-map?lat=48.8584&lon=2.2945&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://mapsi.dev/v1/static-map",
    params={"lat": 48.8584, "lon": 2.2945, "zoom": 15, "width": 600, "height": 400},
    headers={"X-API-Key": "YOUR_API_KEY"}
)
with open("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 /v1/batch/geocode

Request Body

Field	Type	Required	Description
`addresses`	array	Yes	Array of address strings. Max: 5,000 (Growth) or 30,000 (Business)
`countries`	string	No	Optional. Comma-separated ISO country codes (max 4)
`limit`	integer	No	Results per address (default: 1)

📊 Batch Limits by Plan

Growth: Up to 5,000 records per batch
Business: Up to 30,000 records per batch

cURL

curl -X POST "https://mapsi.dev/v1/batch/geocode" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "Eiffel Tower, Paris",
      "Big Ben, London",
      "Colosseum, Rome"
    ],
    "limit": 1
  }'

# With optional country filter:
curl -X POST "https://mapsi.dev/v1/batch/geocode" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": ["4 Avenue de la Madone, Monaco"],
    "countries": "MC",
    "limit": 1
  }'

JavaScript

// Batch geocode multiple addresses (global search)
const response = await fetch('https://mapsi.dev/v1/batch/geocode', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    addresses: [
      'Eiffel Tower, Paris',
      'Big Ben, London',
      'Colosseum, Rome'
    ],
    limit: 1
  })
});
const results = await response.json();
console.log(results);

Python

import requests

# Batch geocode multiple addresses (global search)
response = requests.post(
    "https://mapsi.dev/v1/batch/geocode",
    json={
        "addresses": [
            "Eiffel Tower, Paris",
            "Big Ben, London",
            "Colosseum, Rome"
        ],
        "limit": 1
    },
    headers={"X-API-Key": "YOUR_API_KEY"}
)
results = response.json()
print(results)