API Documentation

Complete guide to using the Map API for geocoding and location services

Quick Start

Register an account at /register
Login to get your JWT token
Create an API key from the API Keys page
Use your API key and secret key to make requests

Authentication

All geo API requests require authentication using your API key and secret key. Include these headers with every request:

X-API-Key: ak_your_api_key_here

X-Secret-Key: sk_your_secret_key_here

You can generate API keys from your API Keys page after logging in.

Credits System

Each API call costs credits. All endpoints cost 1 credit per request:

Autocomplete search: 1 credit
Distance matrix: 1 credit
Place details: 1 credit

All accounts start with 5,000 free credits. Monitor your usage on the dashboard.

Autocomplete API

Search for places and addresses

Endpoint:GET /api/map/autocomplete

Parameters:

q (required): Search query (address, place name, etc.)

Example Request:

const url = 'https://your-api.com/api/map/autocomplete';
const params = {
  q: 'New York'
};
const fullUrl = url + '?' + new URLSearchParams(params).toString();

const response = await fetch(fullUrl, {
  headers: {
    'X-API-Key': 'ak_your_api_key',
    'X-Secret-Key': 'sk_your_secret_key'
  }
});
const data = await response.json();
console.log(data);

Success Response (200):

{
  "source": "cache",
  "count": 5,
  "places": [
    {
      "name": "New York",
      "display_name": "New York, New York, USA",
      "place_rank": 12,
      "latlng": "40.7127753,-74.0059728"
    }
  ],
  "credits_used": 1
}

Distance Matrix API

Calculate distances and routes between locations

Endpoint:GET /api/map/distance-matrix

Parameters:

origin (required): Origin coordinates in "lat,lng" format
destination (required): Destination coordinates in "lat,lng" format

Example Request:

const url = 'https://your-api.com/api/map/distance-matrix';
const params = {
  origin: '40.7128,-74.0060',
  destination: '34.0522,-118.2437'
};
const fullUrl = url + '?' + new URLSearchParams(params).toString();

const response = await fetch(fullUrl, {
  headers: {
    'X-API-Key': 'ak_your_api_key',
    'X-Secret-Key': 'sk_your_secret_key'
  }
});
const data = await response.json();
console.log(data);

Success Response (200):

{
  "source": "cache",
  "data": {
    "distance": 3944577.3,
    "duration": 14724.5
  },
  "credits_used": 1
}

Place Details API

Get detailed information about a place

Endpoint:GET /api/map/place-details

Parameters:

place_id (optional): Place ID from autocomplete results
address (optional): Full address string

Either place_id or address is required

Example Request:

const url = 'https://your-api.com/api/map/place-details';
const params = {
  place_id: '123456'
};
const fullUrl = url + '?' + new URLSearchParams(params).toString();

const response = await fetch(fullUrl, {
  headers: {
    'X-API-Key': 'ak_your_api_key',
    'X-Secret-Key': 'sk_your_secret_key'
  }
});
const data = await response.json();
console.log(data);

Error Responses

Status Code	Error Code	Description
401	INVALID_CREDENTIALS	Invalid API key or secret key
402	INSUFFICIENT_CREDITS	Account has insufficient credits
400	MISSING_QUERY	Required 'q' parameter missing
400	MISSING_PARAMETERS	Required parameters missing
400	INVALID_COORDINATES	Invalid latitude/longitude format
404	ROUTE_NOT_FOUND	No route found between the points
500	INTERNAL_ERROR	Internal server error

Error Response Format:

{
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Need Help?

If you have questions about the API or need assistance with integration, check out your dashboard for usage statistics and API call logs.

View Dashboard Manage API Keys