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://dev.mapsi.dev

⚠️ Development Environment

This is the development/staging API. For production, use https://api.mapsi.dev (coming soon).

Authentication

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

X-API-Key: your_api_key_here

Supported 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,IT

Available Countries

🇲🇨 Monaco MC
🇺🇸 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 SE

Geocoding API

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

Endpoint

GET /api/geocode

Parameters

ParameterTypeRequiredDescription
qstringYesAddress or place name to geocode
countriesstringYesComma-separated ISO country codes (1-4). Example: MC or MC,FR
limitintegerNoMaximum number of results (default: 5, max: 10)

Python Example

import requests

class MapsiClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://dev.mapsi.dev"  # Use your environment URL
        self.headers = {"X-API-Key": api_key}
    
    def geocode(self, address, countries, limit=5):
        """
        Geocode an address.
        
        Args:
            address: Address string to geocode
            countries: Required. Comma-separated country codes (1-4)
            limit: Max results (default: 5, max: 10)
        """
        params = {
            "q": address, 
            "countries": countries,  # Required: e.g., "MC" or "MC,FR"
            "limit": limit
        }
        response = requests.get(
            f"{self.base_url}/api/geocode",
            params=params,
            headers=self.headers
        )
        return response.json()

# Usage
client = MapsiClient("your_api_key")
result = client.geocode("4 Avenue de la Madone", "MC")
print(result)

Reverse Geocoding API

Convert geographic coordinates back into human-readable addresses.

Endpoint

GET /api/reverse

Parameters

ParameterTypeRequiredDescription
latfloatYesLatitude coordinate
lonfloatYesLongitude coordinate
countriesstringYesComma-separated ISO country codes (1-4). Example: MC
limitintegerNoMaximum number of results (default: 1)

Python Example

def reverse_geocode(self, lat, lon, countries, limit=1):
    """
    Reverse geocode coordinates to address.
    
    Args:
        lat: Latitude
        lon: Longitude
        countries: Required. Comma-separated country codes (1-4)
        limit: Max results (default: 1)
    """
    params = {
        "lat": lat, 
        "lon": lon,
        "countries": countries,  # Required: e.g., "MC"
        "limit": limit
    }
    response = requests.get(
        f"{self.base_url}/api/reverse",
        params=params,
        headers=self.headers
    )
    return response.json()

# Usage
result = client.reverse_geocode(43.7409, 7.4279, "MC")
print(result)

Places API

Find points of interest, businesses, and landmarks near any location.

Endpoint

GET /api/places

Parameters

ParameterTypeRequiredDescription
qstringYesSearch query (e.g., "coffee", "restaurant")
latfloatYesLatitude for search center
lonfloatYesLongitude for search center
countriesstringYesComma-separated ISO country codes (1-4). Example: MC,FR
limitintegerNoMaximum number of results (default: 5)

Python Example

def find_places(self, query, lat, lon, countries, limit=5):
    """
    Search for places/POIs near a location.
    
    Args:
        query: Search term (e.g., "coffee", "hotel")
        lat: Center latitude
        lon: Center longitude
        countries: Required. Comma-separated country codes (1-4)
        limit: Max results (default: 5)
    """
    params = {
        "q": query,
        "lat": lat, 
        "lon": lon,
        "countries": countries,  # Required: e.g., "MC,FR"
        "limit": limit
    }
    response = requests.get(
        f"{self.base_url}/api/places",
        params=params,
        headers=self.headers
    )
    return response.json()

# Usage
result = client.find_places("casino", 43.7384, 7.4246, "MC")
print(result)

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-map

Parameters

ParameterTypeRequiredDescription
centerstringYesMap center as "lat,lon"
zoomintegerYesZoom level (1-20)
sizestringNoImage size as "widthxheight" (default: 600x400)

Python Example

def get_static_map(self, lat, lon, zoom=14, width=600, height=400):
    """
    Generate a static map image.
    
    Note: This API does NOT require country codes.
    
    Args:
        lat: Center latitude
        lon: Center longitude
        zoom: Zoom level (1-20)
        width: Image width in pixels
        height: Image height in pixels
    """
    params = {
        "lat": lat,
        "lon": lon,
        "zoom": zoom,
        "width": width,
        "height": height
    }
    response = requests.get(
        f"{self.base_url}/api/static-map",
        params=params,
        headers=self.headers
    )
    return response.content

# Usage - save image
map_data = client.get_static_map(43.7384, 7.4246, 15)
with open("monaco_map.png", "wb") as f:
    f.write(map_data)

Batch Geocoding API

Process multiple addresses in a single request for high-throughput applications.

Endpoint

POST /api/batch/geocode

Request Body

FieldTypeRequiredDescription
addressesarrayYesArray of address strings (max: 100)
countriesstringYesComma-separated ISO country codes (1-4). Example: MC
limitintegerNoResults per address (default: 1)

Python Example

def batch_geocode(self, addresses, countries, limit=1):
    """
    Geocode multiple addresses in one request.
    
    Args:
        addresses: List of address strings (max: 100)
        countries: Required. Comma-separated country codes (1-4)
        limit: Results per address (default: 1)
    """
    payload = {
        "addresses": addresses, 
        "countries": countries,  # Required
        "limit": limit
    }
    response = requests.post(
        f"{self.base_url}/api/batch/geocode",
        json=payload,
        headers=self.headers
    )
    return response.json()

# Usage
addresses = [
    "4 Avenue de la Madone, Monaco",
    "Place du Casino, Monte-Carlo"
]
result = client.batch_geocode(addresses, "MC")
print(result)

Routing API

Calculate optimal routes between points with support for different transportation modes.

Endpoint

GET /api/routing

Parameters

ParameterTypeRequiredDescription
start_latfloatYesStarting point latitude
start_lonfloatYesStarting point longitude
end_latfloatYesDestination latitude
end_lonfloatYesDestination longitude
profilestringNoTransportation mode: "car", "foot", "bicycle" (default: "car")

Python Example

def calculate_route(self, start_lat, start_lon, end_lat, end_lon):
    params = {
        "start_lat": start_lat,
        "start_lon": start_lon,
        "end_lat": end_lat,
        "end_lon": end_lon,
        "profile": "car"
    }
    response = requests.get(
        f"{self.base_url}/api/routing",
        params=params,
        headers=self.headers
    )
    return response.json()

# Usage
result = client.calculate_route(40.7484, -73.9857, 40.7580, -73.9855)
print(f"Distance: {result['routes'][0]['distance']} meters")