API Overview

The maps.guru API provides programmatic access to maps, geocoding, and routing services through a RESTful interface.

Base URLs

Request Format

All API requests follow a consistent format:

GET https://api.maps.guru/v1/{service}/{endpoint}?key=mapx_your_key

Content Types

• Request: application/json (for POST/PUT/PATCH)
• Response: application/json (API responses)
• Tiles: application/x-protobuf (vector tiles)

Response Format

All responses include a consistent JSON structure:

{
  "results": [...],
  "metadata": {
    "total": 10,
    "page": 1,
    "limit": 20
  }
}

Error Responses

Errors use standard HTTP status codes with a JSON body:

{
  "statusCode": 400,
  "message": "Invalid query parameter: q is required"
}

Versioning

The API is versioned via the URL path (/v1/). We follow semantic versioning — breaking changes only happen in major version bumps. The current version is v1.

SDKs and Libraries

Official client libraries are available for popular languages:

• JavaScript/TypeScript
• Python
• Go
• CLI