API Reference

Complete reference for the Rasta Mapen Location API. All service endpoints require a valid API key via the x-api-key header.

GeocodingPlacesAutocomplete

API Info

Base URL

https://rasta-mapen-server.vercel.app/api/v1

Authentication

Header: x-api-key: YOUR_KEY

Response Format

JSON (UTF-8)

Rate Limit

500 req/day on Free plan

Quick Start

Get your API Key

Create an account and generate an API key from your dashboard.

Make your first request

Call any endpoint with your API key in the x-api-key header.

Get structured JSON

Every response includes success, data, and optional meta pagination.

Example Request

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/geocode/reverse?lat=23.8103&lon=90.4125" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "coordinates": { "lat": 23.8103, "lon": 90.4125 },
    "division": {
      "name": "Dhaka",
      "coordinates": { "type": "Point", "lat": 23.685, "lon": 90.3563 }
    },
    "district": {
      "name": "Dhaka",
      "coordinates": { "type": "Point", "lat": 23.81, "lon": 90.41 }
    },
    "thana": {
      "name": "Dhanmondi",
      "coordinates": { "type": "Point", "lat": 23.75, "lon": 90.37 }
    },
    "address": "Dhanmondi, Dhaka Sadar, Dhaka, Dhaka Division"
  }
}

Authentication

All service endpoints require a valid API key. You can pass it via request header or query parameter.

Method	Example
Header	x-api-key: rm_live_xxx
Query	?api_key=rm_live_xxx

Base URL

https://rasta-mapen-server.vercel.app/api/v1

Auth Examples

# Via header
curl -H "x-api-key: rm_live_xxx" \
  "https://rasta-mapen-server.vercel.app/api/v1/divisions"

# Via query parameter
curl "https://rasta-mapen-server.vercel.app/api/v1/divisions?api_key=rm_live_xxx"

Try it live

Interactive reverse geocoding

Click anywhere on the map below — we'll call /geocode/reverse and show you the resolved address hierarchy in real time.

Open full map

Map tiles are served free by OpenStreetMap contributors.

Divisions

2 endpoints

GET/api/v1/divisions

API Key

Get all divisions (paginated)

Param	In	Type	Req	Description
page	query	number	no	Page number (default 1)
limit	query	number	no	Per page (max 50, default 20)

Response: Array of divisions + meta pagination

GET/api/v1/divisions/:id

API Key

Get division by MongoDB ObjectId

Param	In	Type	Req	Description
id	path	string	yes	MongoDB ObjectId

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/divisions?limit=8" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": [
    {
      "name": "Dhaka",
      "coordinates": {
        "type": "Point",
        "lat": 23.685,
        "lon": 90.3563
      }
    },
    {
      "name": "Chittagong",
      "coordinates": {
        "type": "Point",
        "lat": 22.3569,
        "lon": 91.7832
      }
    }
  ]
}

Districts

4 endpoints

GET/api/v1/districts

API Key

Get all districts (paginated)

Param	In	Type	Req	Description
page	query	number	no	Page number
limit	query	number	no	Per page (max 50)

GET/api/v1/districts/:id

API Key

Get district by ID

GET/api/v1/districts/division/:name

API Key

Get districts by division name

Param	In	Type	Req	Description
name	path	string	yes	Division name (e.g. Dhaka)

GET/api/v1/districts/division-id/:divisionId

API Key

Get districts by division ID

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/districts/division/Dhaka" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": [
    {
      "name": "Dhaka",
      "coordinates": {
        "type": "Point",
        "lat": 23.81,
        "lon": 90.41
      }
    },
    {
      "name": "Gazipur",
      "coordinates": {
        "type": "Point",
        "lat": 24,
        "lon": 90.43
      }
    }
  ]
}

Sub-Districts

4 endpoints

GET/api/v1/sub-districts

API Key

Get all sub-districts (paginated)

GET/api/v1/sub-districts/:id

API Key

Get sub-district by ID

GET/api/v1/sub-districts/district/:name

API Key

Get sub-districts by district name

GET/api/v1/sub-districts/division/:name

API Key

Get sub-districts by division name

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/sub-districts?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": [
    {
      "name": "Dhaka Sadar",
      "coordinates": {
        "type": "Point",
        "lat": 23.7,
        "lon": 90.37
      }
    },
    {
      "name": "Gazipur Sadar",
      "coordinates": {
        "type": "Point",
        "lat": 24,
        "lon": 90.43
      }
    }
  ]
}

Thanas

5 endpoints

GET/api/v1/thanas

API Key

Get all thanas (paginated)

GET/api/v1/thanas/:id

API Key

Get thana by ID

GET/api/v1/thanas/sub-district/:name

API Key

Get thanas by sub-district name

GET/api/v1/thanas/district/:name

API Key

Get thanas by district name

GET/api/v1/thanas/division/:name

API Key

Get thanas by division name

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/thanas/district/Dhaka" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": [
    {
      "name": "Dhanmondi",
      "coordinates": {
        "type": "Point",
        "lat": 23.75,
        "lon": 90.37
      }
    },
    {
      "name": "Gulshan",
      "coordinates": {
        "type": "Point",
        "lat": 23.79,
        "lon": 90.41
      }
    }
  ]
}

Unions

6 endpoints

GET/api/v1/unions

API Key

Get all unions (paginated)

GET/api/v1/unions/:id

API Key

Get union by ID

GET/api/v1/unions/sub-district/:name

API Key

Get unions by sub-district name

GET/api/v1/unions/thana/:name

API Key

Get unions by thana name

GET/api/v1/unions/district/:name

API Key

Get unions by district name

GET/api/v1/unions/division/:name

API Key

Get unions by division name

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/unions?limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": [
    {
      "name": "Mashka",
      "coordinates": {
        "type": "Point",
        "lat": 24.667,
        "lon": 90.8
      }
    },
    {
      "name": "Baliadi",
      "coordinates": {
        "type": "Point",
        "lat": 24.1,
        "lon": 90.25
      }
    }
  ]
}

Places

7 endpoints

GET/api/v1/places

API Key

Get all places (paginated, filterable)

Param	In	Type	Req	Description
page	query	number	no	Page number
limit	query	number	no	Per page (max 50)
type	query	string	no	Filter by place type (e.g. restaurant)
district	query	string	no	Filter by district name

GET/api/v1/places/lookup

API Key

Smart lookup: find the place at lat/lon from cache, or fetch from Google Places and store it for next time.

Param	In	Type	Req	Description
lat	query	number	yes	Latitude
lon	query	number	yes	Longitude
radius	query	number	no	Match radius in meters (default 60)

Response: { place, source: "db" | "google" | "none", isNew: boolean }

GET/api/v1/places/search

API Key

Search places by name

Param	In	Type	Req	Description
q	query	string	yes	Search query (min 2 chars)
limit	query	number	no	Max results (default 10)

GET/api/v1/places/nearby

API Key

Find nearby places using geospatial query

Param	In	Type	Req	Description
lat	query	number	yes	Latitude
lng	query	number	yes	Longitude
radius	query	number	no	Radius in meters (default 1000)
type	query	string	no	Filter by place type

GET/api/v1/places/district/:name

API Key

Get places by district name

GET/api/v1/places/type/:type

API Key

Get places by type

GET/api/v1/places/:id

API Key

Get place by ID

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/places/search?q=restaurant&limit=5" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": [
    {
      "name": "Star Kabab",
      "coordinates": {
        "lat": 23.75,
        "lon": 90.38
      }
    },
    {
      "name": "Pizza Hut",
      "coordinates": {
        "lat": 23.79,
        "lon": 90.41
      }
    }
  ]
}

Geocoding

3 endpoints

GET/api/v1/geocode/reverse

API Key

Reverse geocode — coordinates to full address hierarchy

Param	In	Type	Req	Description
lat	query	number	yes	Latitude
lon	query	number	yes	Longitude

Response: Division → District → Sub-district → Thana → Union + nearby places + formatted address

GET/api/v1/geocode/search

API Key

Forward geocode — search all entities by name

Param	In	Type	Req	Description
q	query	string	yes	Search query (min 2 chars)
limit	query	number	no	Max results (default 10)

Response: Array of results with type, name, coordinates

GET/api/v1/geocode/autocomplete

API Key

Fast prefix search for real-time typing

Param	In	Type	Req	Description
q	query	string	yes	Search prefix
limit	query	number	no	Max results (default 8)

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/geocode/reverse?lat=23.8103&lon=90.4125" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "message": "Reverse geocoding successful",
  "data": {
    "coordinates": {
      "lat": 23.8103,
      "lon": 90.4125
    },
    "division": {
      "name": "Dhaka",
      "coordinates": {
        "type": "Point",
        "lat": 23.685,
        "lon": 90.3563
      }
    },
    "district": {
      "name": "Dhaka",
      "coordinates": {
        "type": "Point",
        "lat": 23.81,
        "lon": 90.41
      }
    },
    "sub_district": {
      "name": "Dhaka Sadar",
      "coordinates": {
        "type": "Point",
        "lat": 23.7,
        "lon": 90.37
      }
    },
    "thana": {
      "name": "Dhanmondi",
      "coordinates": {
        "type": "Point",
        "lat": 23.75,
        "lon": 90.37
      }
    },
    "union": null,
    "nearby_places": [
      {
        "name": "Dhanmondi Lake",
        "coordinates": {
          "lat": 23.7465,
          "lon": 90.3736
        }
      }
    ],
    "address": "Dhanmondi, Dhaka Sadar, Dhaka, Dhaka Division"
  }
}

Ward Zones

3 endpoints

GET/api/v1/ward-zones

API Key

Get all ward zones (paginated)

GET/api/v1/ward-zones/city/:city

API Key

Get ward zone by city name

Param	In	Type	Req	Description
city	path	string	yes	City name (e.g. Chattogram)

GET/api/v1/ward-zones/:id

API Key

Get ward zone by ID

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/ward-zones/city/Dhaka" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": {
    "city": "Dhaka",
    "total_zones": 10,
    "total_wards": 129,
    "areas": [
      "Dhanmondi",
      "Gulshan",
      "Mirpur"
    ],
    "zones": [
      {
        "zone": 1,
        "centroid": {
          "lat": 23.81,
          "lon": 90.41
        },
        "wards": [
          1,
          2,
          3,
          4,
          5
        ],
        "ward_count": 5
      }
    ]
  }
}

Routing

5 endpoints

GET/api/v1/routing/route

API Key

Turn-by-turn directions between two coordinates. Returns distance, duration, and (optionally) per-step instructions plus a GeoJSON LineString geometry.

Param	In	Type	Req	Description
from	query	string	yes	Origin "lat,lng"
to	query	string	yes	Destination "lat,lng"
via	query	string	no	Optional waypoints "lat,lng;lat,lng"
profile	query	string	no	driving \| walking \| cycling (default: driving)
steps	query	boolean	no	Include per-step instructions
alternatives	query	boolean	no	Suggest alternative routes
overview	query	string	no	simplified \| full \| false
geometries	query	string	no	geojson \| polyline \| polyline6

Response: distance_m, duration_s, geometry, legs[], waypoints

POST/api/v1/routing/route

API Key

Same as GET /routing/route but accepts an array of coordinates in the body (more than two waypoints, or coordinates that would overflow a query string).

Param	In	Type	Req	Description
coordinates	body	array	yes	Array of {lat, lng} (min 2)
profile	body	string	no	driving \| walking \| cycling
steps	body	boolean	no	Include per-step instructions
alternatives	body	boolean	no	Suggest alternative routes

GET/api/v1/routing/nearest

API Key

Snap a single point to the nearest road on the routing network.

Param	In	Type	Req	Description
lat	query	number	yes	Latitude
lng	query	number	yes	Longitude
profile	query	string	no	driving \| walking \| cycling

POST/api/v1/routing/match

API Key

Snap a noisy GPS trace to the road network. Returns matched route segments.

Param	In	Type	Req	Description
coordinates	body	array	yes	Array of {lat, lng}
timestamps	body	array	no	Per-coordinate epoch seconds (improves quality)
profile	body	string	no	driving \| walking \| cycling

POST/api/v1/routing/table

API Key

Distance / duration matrix between many coordinates (one-to-many or many-to-many).

Param	In	Type	Req	Description
coordinates	body	array	yes	Array of {lat, lng}
sources	body	array	no	Indices into coordinates to use as sources
destinations	body	array	no	Indices into coordinates to use as destinations
annotations	body	string	no	duration \| distance \| duration,distance

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/routing/route" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": [
    "..."
  ]
}

Roads

3 endpoints

GET/api/v1/roads/nearest

API Key

Find the road segment whose centerline is closest to a lat/lng.

Param	In	Type	Req	Description
lat	query	number	yes	Latitude
lng	query	number	yes	Longitude (lon also accepted)
maxMeters	query	number	no	Search radius in meters (default 200)

Response: Road document with name, highway class, ref, length_m, GeoJSON LineString

GET/api/v1/roads/in-bbox

API Key

List road segments overlapping a bounding-box viewport. Useful for drawing a road overlay on a map.

Param	In	Type	Req	Description
minLat	query	number	yes	Bounding box south latitude
minLng	query	number	yes	Bounding box west longitude
maxLat	query	number	yes	Bounding box north latitude
maxLng	query	number	yes	Bounding box east longitude
limit	query	number	no	Cap results (default 500, max 2000)
classes	query	string	no	Comma-separated highway classes filter, e.g. "motorway,primary"

GET/api/v1/roads/search

API Key

Full-text search across road name + ref (e.g. "N1", "Mirpur Road").

Param	In	Type	Req	Description
q	query	string	yes	Search query
limit	query	number	no	Cap results (default 20, max 100)

Code Example

curl -X GET "https://rasta-mapen-server.vercel.app/api/v1/roads/nearest" \
  -H "x-api-key: YOUR_API_KEY"

Sample Response

{
  "success": true,
  "data": [
    "..."
  ]
}

Rate Limiting

API requests are rate-limited based on your subscription plan. Exceeding your limit returns 429 Too Many Requests.

Plan	Daily	Monthly
Free	500	15,000
Starter	5,000	150,000
Growth	25,000	750,000
Enterprise	100,000	3,000,000

Limits reset at midnight UTC. Check X-RateLimit-Remaining header for real-time usage.

Rate Limit Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 423
X-RateLimit-Reset: 1712361600

---

HTTP/1.1 429 Too Many Requests
{
  "success": false,
  "message": "Daily limit exceeded",
  "retryAfter": "2024-04-06T00:00:00Z"
}

Error Codes

Code	Meaning
200	Success
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
429	Rate Limited — daily or monthly limit exceeded
500	Server Error — something went wrong

Error Response Format

{
  "success": false,
  "message": "Invalid API key",
  "errorMessages": [
    {
      "path": "x-api-key",
      "message": "API key is missing or invalid"
    }
  ]
}

{
  "success": false,
  "message": "Validation error",
  "errorMessages": [
    {
      "path": "lat",
      "message": "Latitude is required"
    },
    {
      "path": "lon",
      "message": "Longitude is required"
    }
  ]
}