# Mapsi API Documentation for LLMs
# Last Updated: February 2026
# Base URL: https://mapsi.dev

## Overview

Mapsi provides enterprise-grade geocoding and mapping APIs with global coverage.
All APIs support worldwide address search. Country codes are OPTIONAL.
All API endpoints use the /v1/ prefix.

## Authentication

All requests require an API key in the header:
X-API-Key: your_api_key_here

## Rate Limits

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

---

## API Endpoints

### 1. Geocoding API
Convert addresses to coordinates.

**Endpoint:** GET /v1/geocode

**Parameters:**
- q (required): Address or place name to geocode
- countries (optional): Comma-separated ISO country codes (max 4). Example: FR,DE
- limit (optional): Max results (default: 5, max: 25)
- lang (optional): Response language (default: en)

**Example:**
```
GET /v1/geocode?q=Eiffel+Tower+Paris&limit=5
X-API-Key: YOUR_API_KEY
```

**With country filter:**
```
GET /v1/geocode?q=Eiffel+Tower+Paris&countries=FR&limit=5
X-API-Key: YOUR_API_KEY
```

---

### 2. Autocomplete API
Get real-time address suggestions as users type.

**Endpoint:** GET /v1/autocomplete

**Parameters:**
- q (required): Partial address text
- countries (optional): Comma-separated ISO country codes (max 4)
- limit (optional): Max suggestions (default: 5, max: 10)
- lang (optional): Response language (default: en)

**Example:**
```
GET /v1/autocomplete?q=main+str&limit=5
X-API-Key: YOUR_API_KEY
```

---

### 3. Reverse Geocoding API
Convert coordinates to addresses.

**Endpoint:** GET /v1/reverse

**Parameters:**
- lat (required): Latitude coordinate
- lon (required): Longitude coordinate
- countries (optional): Comma-separated ISO country codes (max 4)
- limit (optional): Max results (default: 1, max: 10)

**Example:**
```
GET /v1/reverse?lat=48.8584&lon=2.2945
X-API-Key: YOUR_API_KEY
```

---

### 4. Places API
Find points of interest near a location.

**Endpoint:** GET /v1/places

**Parameters:**
- q (required): Search query (e.g., "restaurant", "hotel")
- lat (optional): Latitude for search center
- lon (optional): Longitude for search center
- countries (optional): Comma-separated ISO country codes (max 4)
- limit (optional): Max results (default: 10)

**Example:**
```
GET /v1/places?q=restaurant&lat=48.8584&lon=2.2945
X-API-Key: YOUR_API_KEY
```

---

### 5. Static Maps API
Generate static map images.

**Endpoint:** GET /v1/static-map

**Parameters:**
- lat (required): Center latitude
- lon (required): Center longitude
- zoom (optional): Zoom level (default: 14)
- width (optional): Image width in pixels (default: 600)
- height (optional): Image height in pixels (default: 400)

**Example:**
```
GET /v1/static-map?lat=48.8584&lon=2.2945&zoom=15&width=600&height=400
X-API-Key: YOUR_API_KEY
```

---

### 6. Batch Geocoding API
Geocode multiple addresses in a single request.

**Endpoint:** POST /v1/batch/geocode

**Request Body (JSON):**
- addresses (required): Array of address strings
- countries (optional): Comma-separated ISO country codes
- limit (optional): Results per address (default: 1)

**Batch Limits:**
- Growth plan: Up to 5,000 records per batch
- Business plan: Up to 30,000 records per batch

**Example:**
```
POST /v1/batch/geocode
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "addresses": [
    "Eiffel Tower, Paris",
    "Big Ben, London",
    "Colosseum, Rome"
  ],
  "limit": 1
}
```

---

## Response Format

All APIs return JSON responses with the following structure:

**Success Response:**
```json
{
  "success": true,
  "results": [...],
  "count": 5,
  "_response_time_ms": 45
}
```

**Error Response:**
```json
{
  "success": false,
  "error": "Error description",
  "code": "ERROR_CODE"
}
```

---

## Country Codes

Country codes use ISO 3166-1 alpha-2 format (2-letter codes).
Examples: US, GB, FR, DE, IT, ES, NL, BE, CH, AT, AU, CA

**Note:** Country codes are OPTIONAL for all APIs. If omitted, search is performed globally.

---

## Code Examples

### JavaScript
```javascript
// Geocode an address
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);
```

### Python
```python
import requests

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"])
```

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

---

## Support

Email: sales@mapsi.dev
Website: https://mapsi.dev
Documentation: https://mapsi.dev/docs

© 2026 Mapsi. All rights reserved.