API Documentation

Authentication

Server Information

Base URL: https://maps.powermap.live

To access the API, request an OAuth2 access token using the Client Credentials flow with the Client ID and Client Secret.

POST /oauth/token

Parameters

Field	Value	Description
`grant_type`	`client_credentials`	Grant type for server-to-server auth.
`client_id`	`your_client_id`	Your Client ID.
`client_secret`	`your_client_secret`	Your Client Secret.

Example Response

{
  "token_type": "bearer",
  "access_token": "c7cfd7f0a148e11ef399fe5c1d0d6f39ab8330c5",
  "expires_in": 86400
}

Using the Token: Include the token in the Authorization header:
Authorization: Bearer <access_token>

1

Geocode

High-performance geocoding with advanced fuzzy search and multi-language support, seamlessly converting addresses and place names into precise geographic coordinates.

GET /api/v2/map/geocode

Query Parameters

Parameter	Type	Required	Description
`q`	`string`	Yes	Search query term. Example: `เซ็นทรัลเวิลด์`.
`coor`	`string`	No	Bias results around this coordinate. Example: `14.24,100.59` (`lat,lng` order).
`skip`	`number`	No	Number of records to skip for pagination. Default: `0`.
`take`	`number`	No	Number of records to return. Default: `20`.

Example Request

GET /api/v2/map/geocode?q=central&coor=14.24,100.59&skip=0&take=1

Example Response

[
    {
        "_index": "poi_pa_20260831_044804",
        "_type": "_doc",
        "_id": "1699152",
        "_score": 14.137453,
        "_source": {
            "gid": 1699152,
            "amphoe_e": "Phra Nakhon Si Ayutthaya",
            "tambon_t": "คลองสวนพลู",
            "address_t": "129 ถ.สายเอเชีย ต.คลองสวนพลู อ.พระนครศรีอยุธยา จ.พระนครศรีอยุธยา",
            "rdg_ename": null,
            "_meta": {},
            "amphoe_t": "พระนครศรีอยุธยา",
            "moo": null,
            "vill_tname": null,
            "name_e": "Central Ayutthaya",
            "vill_ename": null,
            "province_e": "Phra Nakhon Si Ayutthaya",
            "rdm_tname": "สายเอเชีย",
            "tambon_e": "Khlong Suan Phlu",
            "soim_ename": null,
            "new_cate": 4601,
            "soiv_tname": null,
            "province_t": "พระนครศรีอยุธยา",
            "coordinates": [
                100.61230969320958,
                14.331027166877663
            ],
            "rdg_tname": null,
            "post_code": 13000,
            "house_no": "129",
            "rdm_ename": "Asia",
            "soiv_ename": null,
            "geometry": {
                "crs": {
                    "type": "name",
                    "properties": {
                        "name": "EPSG:4326"
                    }
                },
                "coordinates": [
                    100.61230969320958,
                    14.331027166877663
                ],
                "type": "Point"
            },
            "address_e": "129 Asia Rd., Khlong Suan Phlu, Phra Nakhon Si Ayutthaya, Phra Nakhon Si Ayutthaya",
            "name_t": "เซ็นทรัล อยุธยา",
            "soim_tname": null
        },
        "_meta": {
            "confidence": 83,
            "score_details": {
                "prov_match": false,
                "amp_match": false,
                "text_sim": 0.8,
                "elastic_score": 14.14,
                "distance_km": 10.4
            },
            "processing_method": "Regex"
        }
    }
]

2

Search (Address & POI)

Geocoding and Points of Interest (POI) search. Find places by name, address, or category. Supports language-specific endpoints and location bias.

GET /api/v2/map/address

GET /api/v2/map/address_th

GET /api/v2/map/address_en

Query Parameters

Parameter	Type	Required	Description
`q`	`string`	Yes	Search query term. Example: `7-eleven` or `อาปิโก`.
`coor`	`string`	No	Bias results around this coordinate. Example: `14.24,100.59` (`lat,lng` order).
`skip`	`number`	No	Number of records to skip for pagination. Default: `0`.
`take`	`number`	No	Number of records to return. Max `50`, Default: `20`.

Example Request

GET /api/v2/map/address?q=7-eleven&coor=14.24,100.59&skip=0&take=2

Example Response

[
    {
        "_index": "poi_pa",
        "_type": "_doc",
        "_id": "1681542",
        "_score": 23.560156,
        "_source": {
            "gid": 1681542,
            "amphoe_e": "Bang Pa-in",
            "tambon_t": "บ้านเลน",
            "address_t": null,
            "amphoe_t": "บางปะอิน",
            "name_e": "7-Eleven",
            "province_e": "Phra Nakhon Si Ayutthaya",
            "tambon_e": "Ban Len",
            "province_t": "พระนครศรีอยุธยา",
            "coordinates": [ 100.575884, 14.226746 ],
            "post_code": 13160,
            "address_e": null,
            "name_t": "เซเว่น อีเลฟเว่น",
            "geometry": {
                "type": "Point",
                "coordinates": [ 100.575884, 14.226746 ]
            }
        }
    }
]

Source Object (`_source`)

Field	Type	Description
`gid`	`number`	Global ID of the POI.
`name_t` / `name_e`	`string`	Thai and English name of the place.
`address_t` / `address_e`	`string`	Full address string in Thai/English.
`coordinates`	`[number, number]`	Coordinates in `[lng, lat]` format.
`province_t` / `amphoe_t` / `tambon_t`	`string`	Administrative boundaries (Thai).
`geometry`	`Object`	GeoJSON Feature geometry with `coordinates`.
`new_cate`	`number`	Internal categorization integer.

Language Auto-Detection: The /address endpoint automatically detects whether the query is Thai or English (using franc).
Force Language: Use /address_th to force Thai search or /address_en to force English search.
Coordinate Bias: Notice that the coor query parameter accepts lat,lng order, unlike the response coordinates which are lng,lat.

3

Nearby Search

Search for Points of Interest (POI) near a specific geographical coordinate within a specified radius.

GET /api/v2/map/nearby

Query Parameters

Parameter	Type	Required	Description
`coor`	`string`	Yes	Center coordinates for the search in `lat,lng` order. Example: `14.24,100.59`.
`dist`	`number`	No	Search radius in kilometers. Example: `10`.

Example Request

GET /api/v2/map/nearby?coor=14.24,100.59&dist=10

Example Response

[
    {
        "_index": "poi_pa",
        "_type": "_doc",
        "_id": "412626",
        "_score": null,
        "_source": {
            "gid": 412626,
            "amphoe_e": "Bang Pa-in",
            "tambon_t": "บ้านเลน",
            "amphoe_t": "บางปะอิน",
            "name_e": "Ban Len Nuea",
            "province_e": "Phra Nakhon Si Ayutthaya",
            "tambon_e": "Ban Len",
            "province_t": "พระนครศรีอยุธยา",
            "coordinates": [ 100.587247, 14.244125 ],
            "post_code": 13160,
            "geometry": {
                "type": "Point",
                "coordinates": [ 100.587247, 14.244125 ]
            },
            "name_t": "บ้านเลนเหนือ"
        },
        "sort": [ 0.5462850133254782 ]
    }
]

4

Suggestions (Autocomplete)

Fast autocomplete suggestions for POIs and addresses as the user types. Returns lists of matching names, addresses, and geographic coordinates.

GET /api/v2/map/suggest

Query Parameters

Parameter	Type	Required	Description
`q`	`string`	Yes	Partial input query text to suggest on. Example: `AAPICO`.

Example Request

GET /api/v2/map/suggest?q=AAPICO

Example Response

Returns synchronized arrays for name, addr, and location.

{
    "name": [
        "AAPICO Forging PCL",
        "AAPICO Hitech Parking",
        "AAPICO Hitech PCL"
    ],
    "addr": [
        "Nong Mai Daeng, Mueang Chon Buri, Chon Buri, undefined",
        "Ban Len, Bang Pa-in, Phra Nakhon Si Ayutthaya, undefined",
        "Ban Len, Bang Pa-in, Phra Nakhon Si Ayutthaya, undefined"
    ],
    "location": [
        null,
        null,
        null
    ]
}

5

Road Search

Search for road/street names and geometric definitions. Returns standard ElasticSearch hits including bounding boxes and multiline string geometries.

GET /api/v2/map/road/search

Query Parameters

Parameter	Type	Required	Description
`q`	`string`	Yes	Road name search query. Example: `Phet Kasem 87`.

Example Request

GET /api/v2/map/road/search?q=Phet Kasem 87

Example Response

{
    "took": 1,
    "timed_out": false,
    "hits": {
        "total": { "value": 3, "relation": "eq" },
        "max_score": 1,
        "hits": [
            {
                "_index": "road_pg",
                "_type": "road",
                "_id": "1220487",
                "_score": 1,
                "_source": {
                    "ogc_fid": 1220487,
                    "name_t": "ซ.เพชรเกษม 87",
                    "name_e": "Phet Kasem 87",
                    "geometry": {
                        "type": "MultiLineString",
                        "coordinates": [ [ [100.3239, 13.7033], [100.3241, 13.7013] ] ]
                    },
                    "bbox": [ 100.3239, 13.7013, 100.3241, 13.7033 ]
                }
            }
        ]
    }
}

6

Road Suggest

Retrieve fast autocomplete suggestions for road networks.

GET /api/v2/map/road/suggest

Query Parameters

Parameter	Type	Required	Description
`q`	`string`	Yes	Partial input query text to suggest on. Example: `เพชรเกษม 87`.

Example Request

GET /api/v2/map/road/suggest?q=เพชรเกษม 87

Example Response

{
    "took": 1,
    "timed_out": false,
    "hits": {
        "total": { "value": 1, "relation": "eq" },
        "max_score": 1,
        "hits": [
            {
                "_index": "road_pg",
                "_type": "road",
                "_id": null,
                "_score": 1,
                "_source": {
                    "name_t": "ซ.เพชรเกษม 87",
                    "name_e": "Phet Kasem 87"
                }
            }
        ]
    }
}

7

Category Search

Retrieve the list of base administrative or venue categories, drill down into subcategories, and search for Points of Interest specifically by their category ID. Ideal for building directory or filter features.

GET /api/v2/map/category/major

GET /api/v2/map/category/sub

Category APIs Overview

The category structure natively supports two levels of hierarchy: Major Categories and Subcategories.

Endpoint	Description	Required Params
`/category/major`	Returns all primary (major) category groups, e.g., "Dwelling", "Medical", "Attractions".	None
`/category/sub`	Returns all subcategories linking back to their major category via `parent_id`., e.g., "Townhouse", "Hospital".	None

Example Response (Subcategory)

Notice how parent_id points matching ID in the /category/major list.

[
    {
        "id": 1001,
        "name_en": "Single-family house",
        "name_th": "บ้านเดี่ยว",
        "parent_id": 1000
    },
    {
        "id": 1002,
        "name_en": "Townhouse",
        "name_th": "ทาวเฮาส์",
        "parent_id": 1000
    },
    {
        "id": 8213,
        "name_en": "Archaeological site / Historic Building or Place",
        "name_th": "โบราณสถาน / สถานที่ทางประวัติศาสตร์",
        "parent_id": 8200
    }
]

Search for places specifically by their category ID along with geographic distance filtering.

GET /api/v2/map/cate_v2

Query Parameters

Parameter	Type	Required	Description
`type`	`number`	Yes	The specific category or subcategory ID to search for. Example: `6003` (Dental Clinic)
`coor`	`string`	Yes	Center coordinates for the search in `lat,lng` order. Example: `14.24,100.59`.
`dist`	`number`	Yes	Search radius constraint in kilometers. Example: `5`. Only respected if `coor` is given.
`skip`	`number`	No	Number of records to skip for pagination. Default: `0`.
`take`	`number`	No	Number of records to return. Max `50`, Default: `20`.

Example Request

GET /api/v2/map/cate_v2?coor=14.24,100.59&dist=5&type=6003

Example Response

Returns full POI records matching the category filter along with detailed properties as it appear in normal search endpoints.

[
    {
        "_index": "poi_pa",
        "_type": "_doc",
        "_id": "2104641",
        "_score": null,
        "_source": {
            "gid": 2104641,
            "amphoe_e": "Bang Pa-in",
            "tambon_t": "บ้านเลน",
            "amphoe_t": "บางปะอิน",
            "name_e": "Home Dental Clinic",
            "province_e": "Phra Nakhon Si Ayutthaya",
            "tambon_e": "Ban Len",
            "new_cate": 6003,
            "province_t": "พระนครศรีอยุธยา",
            "coordinates": [ 100.579586, 14.217947 ],
            "post_code": 13160,
            "geometry": {
                "type": "Point",
                "coordinates": [ 100.579586, 14.217947 ]
            },
            "name_t": "คลินิกบ้านทันตกรรม"
        },
        "sort": [ 2.6967869578515145 ]
    }
]

8

Category Major

Retrieve the list of base administrative or venue categorical groups (Level 1).

GET /api/v2/map/category/major

Example Response

[
    {
        "id": 1000,
        "name_en": "Dwelling",
        "name_th": "ที่อยู่อาศัย"
    },
    {
        "id": 1100,
        "name_en": "Dwelling",
        "name_th": "ที่อยู่อาศัย"
    },
    {
        "id": 1600,
        "name_en": "Building",
        "name_th": "อาคารสำนักงาน"
    }
]

9

Category Sub

Retrieve all subcategories linking back to their major category via parent_id.

GET /api/v2/map/category/sub

Example Response

Notice how parent_id points matching ID in the /category/major list.

[
    {
        "id": 1001,
        "name_en": "Single-family house",
        "name_th": "บ้านเดี่ยว",
        "parent_id": 1000
    },
    {
        "id": 1002,
        "name_en": "Townhouse",
        "name_th": "ทาวเฮาส์",
        "parent_id": 1000
    },
    {
        "id": 8213,
        "name_en": "Archaeological site / Historic Building or Place",
        "name_th": "โบราณสถาน / สถานที่ทางประวัติศาสตร์",
        "parent_id": 8200
    }
]

10

Reverse Geocoding

Convert geographic coordinates into a human-readable administrative area (Sub District, District, Province, and Postcode).

GET /api/v2/map/reverse-geo

Query Parameters

Parameter	Type	Required	Description
`lat`	`number`	Yes	Latitude coordinate. Example: `14.24`
`lon`	`number`	Yes	Longitude coordinate. Example: `100.59`

Example Request

GET /api/v2/map/reverse-geo?lat=14.24&lon=100.59

Example Response

{
    "tam_id": "140601",
    "amp_id": "1406",
    "prov_id": "14",
    "postcode": "13160",
    "tambon_t": "บ้านเลน",
    "tambon_e": "Ban Len",
    "amphoe_t": "บางปะอิน",
    "amphoe_e": "Bang Pa-in",
    "province_t": "พระนครศรีอยุธยา",
    "province_e": "Phra Nakhon Si Ayutthaya",
    "region": "Central",
    "input": {
        "lat": 14.24,
        "lon": 100.59
    }
}

11

Speed Limit

Retrieve the legal speed limit for a given geographic coordinate based on the nearest road segment.

GET /api/v2/map/speed-limit

Query Parameters

Parameter	Type	Required	Description
`lat`	`number`	Yes	Latitude coordinate. Example: `13.75`
`lon`	`number`	Yes	Longitude coordinate. Example: `100.522`

Example Request

GET /api/v2/map/speed-limit?lat=13.75&lon=100.522

Example Response

Returns the speed limit in km/h and the distance setup to the nearest matched road segment in meters.

{
    "speed": 150,
    "dist_m": 4.887309256581593,
    "input": {
        "lat": 13.75,
        "lon": 100.522
    }
}

12

Routing

Real-time turn-by-turn navigation API. The response structure is fully compatible with MapLibre and Mapbox Navigation SDKs out of the box, delivering detailed visual banner cues and voice instructions. Note: This endpoint does not support alternative routes. For requests with a large number of waypoints, please use the Standard Routing (POST) API to avoid URL length limitations.

GET /api/v2/map/route/:profile/:coordinates

Path Parameters

Parameter	Type	Required	Description
`profile`	`string`	Yes	One of: `car`, `bike`, `foot`, `motorcycle`.
`coordinates`	`string`	Yes	Semicolon-separated `lng,lat` pairs. Example: `100.523,13.745;100.679,13.812`

Query Parameters (all optional)

Parameter	Type	Default	Description
`language`	`string`	`th`	Language for instruction text.
`steps`	`string`	`true`	Include turn-by-turn steps.
`geometries`	`string`	`polyline6`	Geometry encoding format.
`overview`	`string`	`full`	Detail level: `full`, `simplified`, or `false`.
`voice_instructions`	`string`	`true`	Include voice cues.
`banner_instructions`	`string`	`true`	Include visual banner cues.

Example Request

GET /api/v2/map/route/car/100.5234,13.7456;100.6789,13.8123?language=th

Example Response

{
  "code": "Ok",
  "routes": [{
    "distance": 25432.5,
    "duration": 1842.3,
    "geometry": "ca}uAao~dR... (encoded polyline, precision 6)",
    "legs": [{
      "distance": 25432.5,
      "duration": 1842.3,
      "steps": [
        {
          "distance": 1686.5,
          "duration": 121.4,
          "name": "ถนนพหลโยธิน",
          "maneuver": {
            "type": "turn",
            "modifier": "left",
            "instruction": "เลี้ยวซ้ายเข้า ถนนพหลโยธิน",
            "location": [100.5240, 13.7460]
          },
          "voiceInstructions": [...],
          "bannerInstructions": [...]
        },
        "..."
      ]
    }]
  }],
  "waypoints": [
    { "name": "", "location": [100.5234, 13.7456] },
    { "name": "", "location": [100.6789, 13.8123] }
  ]
}

Error Responses

Status Code	Description
`400 Bad Request`	Invalid coordinates format or unsupported profile.
`422 Unprocessable`	Route could not be calculated (disconnected points).
`502 Bad Gateway`	Routing engine is unreachable.

Polyline Precision: Returns polylines with precision 6 by default.
Profiles: Available: car, bike, foot, motorcycle.
Coordinates Order: [longitude, latitude] format throughout.

13

Routing (Standard)

Real-time turn-by-turn navigation API for calculating distances, ETAs, and rendering routes on web maps. It supports alternative route calculations and allows passing a massive amount of waypoints.

POST /api/v2/map/route/

Request Body Parameters

Field	Type	Required	Description
`points`	`Array`	Yes	Array of target coordinates in `[longitude, latitude]` format.
`profile`	`String`	Yes	One of: `car`, `bike`, `foot`, `motorcycle`, `scooter`.
`elevation`	`Boolean`	No	Enable elevation info for paths. (Default: false)
`instructions`	`Boolean`	No	Include turn-by-turn steps. (Default: true)
`locale`	`String`	No	Language for instruction text (e.g. `th`, `en_US`).
`points_encoded`	`Boolean`	No	Enable polyline6 encoded format for geometry. (Default: true)
`alternative_route.max_paths`	`Integer`	No	Request alternative routes (max allowed is typically 3).
`algorithm`	`String`	No	Set to `alternative_route` when requiring multiple paths.
`snap_preventions`	`Array`	No	Avoid snapping to specific types, e.g., `["ferry", "tollway"]`.

Example Request

curl -X POST "https://maps.powermap.live/api/v2/map/route/" \
  -H "Content-Type: application/json" \
  -H "apikey: {YOUR_API_KEY}" \
  -d '{
    "points": [
      [100.11974950306276, 14.39920155885676],
      [100.69927831165649, 14.183613487315696]
    ],
    "profile": "car",
    "elevation": true,
    "debug": false,
    "instructions": true,
    "locale": "th",
    "optimize": "false",
    "points_encoded": true,
    "snap_preventions": ["ferry"],
    "details": ["road_class", "road_environment", "max_speed", "average_speed"],
    "alternative_route.max_paths": 3,
    "algorithm": "alternative_route"
  }'

Example Response

{
  "paths": [
    {
      "distance": 91516.511,
      "weight": 10822.572461,
      "time": 4416423,
      "transfers": 0,
      "points_encoded": true,
      "bbox": [
        100.119123,
        14.183612,
        100.73033,
        14.409194
      ],
      "points": "c`{vAooabR_i... (encoded polyline)",
      "instructions": [
        {
          "distance": 1686.5,
          "heading": 89.9,
          "sign": 7,
          "interval": [0, 1],
          "text": "Continue onto ถนนพหลโยธิน",
          "time": 121400,
          "street_name": "ถนนพหลโยธิน"
        }
      ]
    },
    {
      "distance": 98210.0,
      "time": 5012300,
      "points": "af_~A{h... (Alternative route)",
      "instructions": [...]
    }
  ]
}

Error Responses

Status Code	Description
`400 Bad Request`	Invalid JSON payload, missing points, or unsupported profile.
`422 Unprocessable`	Route could not be calculated (disconnected points or out of bounds).
`502 Bad Gateway`	Routing engine is unreachable or responded invalidly.

14

Vehicle Routing Problem (VRP)

Advanced fleet optimization via the VROOM engine. Solves complex scenarios involving multiple vehicles, time windows, capacities, skills, and more. Ideal for large-scale logistics and multi-fleet management.

POST /api/v2/map/vrp

Request Body (VROOM Format)

Field	Type	Required	Description
`vehicles`	`Array`	Yes	List of vehicles with capacities, start/end locations.
`jobs`	`Array`	No	Single-location tasks (deliveries, pickups).
`shipments`	`Array`	No	Tasks requiring both pickup and delivery.
`options`	`Object`	No	Options (e.g., `"g": true` for geometry).

Example Request

{
  "vehicles": [{
    "id": 1, "profile": "car",
    "start": [100.5234, 13.7456],
    "end": [100.5234, 13.7456],
    "capacity": [4]
  }],
  "jobs": [
    { "id": 1, "location": [100.5500, 13.7600], "delivery": [1], "service": 300 },
    { "id": 2, "location": [100.5800, 13.7900], "delivery": [2], "service": 300 }
  ],
  "options": { "g": true }
}

Response Body (VROOM Format)

Field	Type	Description
`code`	`number`	Status code (`0` = success).
`summary`	`Object`	High-level summary (total distance, duration, unassigned, computing time).
`unassigned`	`Array`	Jobs/shipments that could not be serviced.
`routes`	`Array`	Ordered list of steps and geometry for each vehicle.

Example Response

{
  "code": 0,
  "summary": {
    "cost": 6512,
    "unassigned": 0,
    "delivery": [3],
    "amount": [3],
    "setup": 0,
    "service": 600,
    "duration": 6512,
    "waiting_time": 0,
    "distance": 89400,
    "computing_times": { "loading": 28, "solving": 8, "routing": 6 }
  },
  "unassigned": [],
  "routes": [{
    "vehicle": 1,
    "cost": 6512,
    "duration": 6512,
    "distance": 89400,
    "steps": [
      { "type": "start", "location": [100.5234, 13.7456], "load": [3], "arrival": 0, "duration": 0, "distance": 0 },
      { "type": "job", "id": 1, "location": [100.5500, 13.7600], "service": 300, "load": [2], "arrival": 1500, "duration": 1500, "distance": 25000 },
      { "type": "job", "id": 2, "location": [100.5800, 13.7900], "service": 300, "load": [0], "arrival": 3512, "duration": 3212, "distance": 45000 },
      { "type": "end", "location": [100.5234, 13.7456], "load": [0], "arrival": 7112, "duration": 6512, "distance": 89400 }
    ],
    "geometry": "...encoded_polyline..."
  }]
}

Error Responses

Status Code	Description
`400 Bad Request`	Invalid payload. Maps to VROOM Code 2.
`422 Unprocessable`	Routing Error. Maps to VROOM Code 3.
`502 Bad Gateway`	Optimization backend is unreachable.

For complete payload structuring, refer to the official VROOM API Documentation.

15

Route Optimize (Multi-Stop)

Optimizes the exact order of multiple stops for a single vehicle to achieve the shortest travel time and distance. Designed specifically for passenger pickup/drop-off scenarios, acting as a simplified facade over the advanced VRP engine.

POST /api/v2/map/route/optimize/

Request Body

Field	Type	Required	Description
`start`	`[number, number]`	Yes	Starting point as `[lng, lat]`.
`end`	`[number, number]`	No	Ending point. If omitted, route ends at last stop.
`stops`	`Array`	Yes	List of stops with `id`, `name`, `location`.

Stops Object

Field	Type	Required	Description
`id`	`number`	Yes	Unique identifier for this stop.
`name`	`string`	No	Display name of the stop.
`location`	`[number, number]`	Yes	Coordinates as `[lng, lat]`.

Example Request

{
  "start": [100.5234, 13.7456],
  "end": [100.6789, 13.8123],
  "stops": [
    { "id": 1, "name": "Pickup A", "location": [100.5500, 13.7600] },
    { "id": 2, "name": "Drop-off B", "location": [100.5800, 13.7900] },
    { "id": 3, "name": "Drop-off C", "location": [100.6200, 13.8000] }
  ]
}

Response Body

Field	Type	Description
`code`	`number`	Status code (`0` = success).
`summary.duration`	`number`	Total travel time in seconds.
`summary.distance`	`number`	Total distance in meters.
`route.steps`	`Array`	Ordered steps: `start` → `stop` → `end`.
`route.geometry`	`string`	Encoded polyline (precision 5).

Steps Object

Each item in route.steps represents a waypoint:

Field	Type	Description
`type`	`string`	`start`, `stop`, or `end`.
`id`	`number`	Stop ID (only for `type: stop`).
`name`	`string`	Stop name.
`location`	`[number, number]`	Coordinates `[lng, lat]`.
`arrival`	`number`	Estimated arrival time (UNIX timestamp).
`duration`	`number`	Cumulative travel time from start (seconds).
`distance`	`number`	Cumulative travel distance from start (meters).

Example Response

{
  "code": 0,
  "summary": {
    "duration": 22734,
    "distance": 418261
  },
  "route": {
    "steps": [
      { "type": "start", "name": "start", "location": [100.5234, 13.7456], "arrival": 1673802000, "duration": 0, "distance": 0 },
      { "type": "stop", "id": 1, "name": "Pickup A", "location": [100.5500, 13.7600], "arrival": 1673804404, "duration": 2404, "distance": 50819 },
      { "type": "stop", "id": 2, "name": "Drop-off B", "location": [100.5800, 13.7900], "arrival": 1673811047, "duration": 9047, "distance": 172378 },
      { "type": "stop", "id": 3, "name": "Drop-off C", "location": [100.6200, 13.8000], "arrival": 1673824734, "duration": 22734, "distance": 418261 },
      { "type": "end", "name": "end", "location": [100.6789, 13.8123], "arrival": 1673825000, "duration": 23000, "distance": 420000 }
    ],
    "geometry": "}mhtA{jxcR... (encoded polyline, precision 5)"
  }
}

Error Responses

Status Code	Description
`400 Bad Request`	Invalid payload or configuration. Maps to VROOM Code 2.
`422 Unprocessable`	Routing Error (disconnected locations). Maps to VROOM Code 3.
`502 Bad Gateway`	Routing engine is unreachable.

16

Route Navigate (Turn-by-Turn)

The ultimate API for Driver Apps. Internally chains Route Optimize (VROOM) and Navigation (GraphHopper) in a single call. It calculates the most optimal stop order and instantly returns Mapbox-compatible turn-by-turn navigation instructions.

Pro Plan Required

POST /api/v2/map/route/optimize/navigate

Request Body

Combines stop optimization with turn-by-turn navigation in a single request. All advanced parameters are optional.

Field	Type	Required	Description
`start`	`[number, number]`	Yes	Vehicle starting point as `[lng, lat]`.
`end`	`[number, number]`	No	Vehicle ending point.
`stops`	`Array`	Yes	Stops with `id`, `name`, `location`. See Stop Parameters below.
`profile`	`String`	No	Routing profile. Default: `car`.
`language`	`String`	No	Language (`th` or `en`). Default: `th`.
Vehicle Optimization Parameters
`capacity`	`Array<int>`	No	Vehicle capacity, e.g. `[4]` for 4 seats or `[4, 100]` for seats + kg.
`speed_factor`	`Number`	No	Speed multiplier. (Default: 1.0)
`max_travel_time`	`Integer`	No	Maximum route duration in seconds.
`time_window`	`[start, end]`	No	Vehicle operating time window (timestamps in seconds).
Per-Stop Parameters (inside `stops[]`)
`stops[].time_windows`	`Array`	No	When the stop must be serviced, e.g. `[[1700000000, 1700003600]]`.
`stops[].service`	`Integer`	No	Service time at stop in seconds.
`stops[].priority`	`Integer`	No	Priority 0–100 (higher = more important).
`stops[].amount`	`Array<int>`	No	Load deposited at this stop. Dimensions must match vehicle `capacity`.
`stops[].skills`	`Array<int>`	No	Required vehicle skills for this stop.
Navigation Parameters
`snap_preventions`	`Array`	No	Avoid snapping to specific types, e.g. `["ferry", "tollway"]`.
`voice_instructions`	`Boolean`	No	Always enabled — required by the navigation engine.
`banner_instructions`	`Boolean`	No	Include visual banner cues. (Default: true)
`voice_units`	`String`	No	`metric` or `imperial`. (Default: metric)

Example Request

{
  "start": [100.70264, 13.758774],
  "end": [100.434594, 13.774903],
  "stops": [
    {
      "id": 1,
      "name": "Pickup A",
      "location": [100.577366, 13.754196],
      "time_windows": [[1700000000, 1700003600]],
      "service": 300,
      "priority": 80,
      "amount": [1]
    },
    {
      "id": 2,
      "name": "Drop-off B",
      "location": [100.558028, 13.766677],
      "service": 120
    },
    {
      "id": 3,
      "name": "Drop-off C",
      "location": [100.6200, 13.8000]
    }
  ],
  "profile": "car",
  "language": "th",
  "capacity": [4],
  "max_travel_time": 7200,
  "snap_preventions": ["ferry"]
}

Response Body

Merges Mapbox-compatible navigation data with VROOM optimization results in a single response.

Field	Type	Description
Navigation (GraphHopper / Mapbox-compatible)
`routes[0].distance`	`number`	Total distance in meters.
`routes[0].duration`	`number`	Total travel time in seconds.
`routes[0].geometry`	`string`	Encoded polyline (precision 6).
`routes[0].legs`	`Array`	One leg per stop-to-stop segment.
`routes[0].legs[].steps`	`Array`	Turn-by-turn instructions for each leg.
Optimization (VROOM)
`optimization.summary`	`Object`	Optimization summary — `cost`, `duration`, `distance`, `service`, `waiting_time`, `unassigned` count.
`optimization.stops`	`Array`	Assigned stops in optimized order. Each item includes `id`, `name`, `location`, `arrival`, `service`, `waiting_time`, `load`.
`optimization.unassigned`	`Array`	Stops that could not be assigned (e.g. exceeded capacity or time window). Each item includes `id`, `name`, `location`.

Example Response (Condensed)

{
  "routes": [{
    "distance": 38770.2,
    "duration": 1938.5,
    "geometry": "encoded_polyline6...",
    "legs": [
      { "distance": 16920, "duration": 780, "steps": ["..."] },
      { "distance": 3960, "duration": 210, "steps": ["..."] },
      { "distance": 17890, "duration": 948, "steps": ["..."] }
    ]
  }],
  "waypoints": [
    { "name": "", "location": [100.700189, 13.758169] },
    { "name": "", "location": [100.577385, 13.754143] },
    { "name": "", "location": [100.557876, 13.766726] },
    { "name": "", "location": [100.434510, 13.774191] }
  ],
  "optimization": {
    "summary": {
      "cost": 2420,
      "duration": 2420,
      "distance": 40929,
      "service": 420,
      "waiting_time": 0,
      "unassigned": 1,
      "delivery": [3],
      "amount": [3]
    },
    "stops": [
      {
        "id": 1,
        "name": "Pickup A",
        "location": [100.577366, 13.754196],
        "arrival": 790,
        "service": 300,
        "waiting_time": 0,
        "load": [2]
      },
      {
        "id": 2,
        "name": "Drop-off B",
        "location": [100.558028, 13.766677],
        "arrival": 1210,
        "service": 120,
        "waiting_time": 0,
        "load": [3]
      }
    ],
    "unassigned": [
      {
        "id": 3,
        "name": "Drop-off C",
        "location": [100.6200, 13.8000]
      }
    ]
  }
}

Leg Steps Object

Field	Type	Description
`maneuver.type`	`string`	`turn`, `depart`, `arrive`, `roundabout`
`maneuver.instruction`	`string`	Human-readable instruction text.
`maneuver.modifier`	`string`	`left`, `right`, `straight`, etc.
`maneuver.location`	`[number, number]`	Coordinates of the maneuver.
`distance`	`number`	Distance for this step (meters).
`duration`	`number`	Duration for this step (seconds).
`voiceInstructions`	`Array`	Voice cues with distance triggers.
`bannerInstructions`	`Array`	Visual banner cues.

Error Responses

Status Code	Description
`400 Bad Request`	Missing or invalid `start`, `stops`.
`403 Forbidden`	This feature requires a Pro plan.
`422 Unprocessable`	Routing Error — disconnected or invalid locations.
`502 Bad Gateway`	Navigation engine is unreachable.

Polyline Precision: Returns polylines with precision 6.
Same Payload: Use the same body for both /optimize and /navigate.
All-in-one: /navigate already calls /optimize internally — no need to call both. Use /optimize alone if you only need the optimized stop order without turn-by-turn directions.

17

EV Routing (Beta)

Calculates an EV-optimized route between an origin and destination, automatically inserting charging stops based on vehicle battery constraints.

Pro Plan Required

POST /api/v2/map/ev/route

Request Body

Field	Type	Required	Description
`origin`	`[number, number]`	Yes	Origin coordinates as `[lng, lat]`.
`destination`	`[number, number]`	Yes	Destination coordinates as `[lng, lat]`.
`locale`	`string`	No	Language code (`th` or `en`). Default: `en`.
`vehicle`	`Object`	No	Vehicle specs (see below).

Vehicle Object

Field	Type	Default	Description
`rangeKm`	`number`	`300`	Total driving range (km) at 100% battery.
`startSocPct`	`number`	`1.0`	State of Charge at origin (0.0–1.0).
`reservePct`	`number`	`0.15`	Minimum SoC buffer during trip.
`arrivalReservePct`	`number`	`0.3`	Desired minimum SoC at destination.
`maxStops`	`number`	`5`	Maximum charging stops to add.
`corridorM`	`number`	`5000`	Max distance (m) for strict candidate. Backup search up to 20km.
`onlyAvailable`	`boolean`	`true`	Only select stations with available chargers.

Example Request

{
  "origin": [100.59518, 14.24418],
  "destination": [101.11923, 12.96296],
  "locale": "en",
  "vehicle": {
    "rangeKm": 350,
    "startSocPct": 0.6,
    "reservePct": 0.2,
    "arrivalReservePct": 0.3,
    "onlyAvailable": false
  }
}

Response Body

Field	Type	Description
`route`	`Object`	GraphHopper route object (distance, time, geometry, instructions).
`stops`	`Array`	Selected charging stations with details.
`message`	`string`	Summary (e.g., "Route calculated with 1 charging stops.").

Route Object (`route.paths[0]`)

Field	Type	Description
`distance`	`number`	Total distance in meters.
`time`	`number`	Total travel time in milliseconds.
`points`	`string`	Encoded polyline (precision 5).
`bbox`	`Array`	Bounding box `[minLon, minLat, maxLon, maxLat]`.
`instructions`	`Array`	Turn-by-turn instructions. Charging stops: `sign: 5` with text "Stop to charge at [Station]".

Stops Object

Field	Type	Description
`id`	`string`	Station PID (external ID).
`name`	`string`	Station name.
`coord`	`[number, number]`	Coordinate `[lng, lat]`.
`detail`	`Object`	Full station details (connectors, address, operator).
`score`	`number`	Internal scoring (lower is better).

Example Response (truncated)

{
  "route": {
    "paths": [{
      "distance": 194242.691,
      "time": 8880107,
      "points": "ca}uAao~dR... (encoded polyline)",
      "bbox": [100.595208, 12.962851, 101.119227, 14.257788],
      "instructions": [
        { "distance": 16.012, "sign": 0, "text": "Continue", "time": 1921, "interval": [0, 1] },
        { "distance": 1686.58, "sign": -2, "text": "Turn left", "time": 121434, "interval": [1, 7] },
        "...",
        { "distance": 0, "sign": 5, "text": "Stop to charge at DHL distribution", "time": 0, "interval": [313, 313] },
        "...",
        { "distance": 0, "sign": 4, "text": "Arrive at destination", "time": 0, "interval": [770, 770] }
      ]
    }]
  },
  "stops": [{
    "id": "cda85310-552f-433d-9de8-f1c7f91538f9",
    "coord": [100.941359, 13.567663],
    "name": "DHL distribution",
    "score": 5514.52,
    "detail": {
      "connectors": [
        { "connector_name": "DHL-1001A", "connector_type": "IEC_62196_T2_COMBO", "max_electric_power": 75, "power_type": "DC", "status": "BLOCKED" },
        { "connector_name": "DHL-1001B", "connector_type": "IEC_62196_T2_COMBO", "max_electric_power": 75, "power_type": "DC", "status": "BLOCKED" }
      ]
    }
  }],
  "message": "Route calculated with 1 charging stops."
}

Error Responses

Status Code	Description
`400 Bad Request`	Missing required fields or invalid format.
`403 Forbidden`	This feature requires a Pro plan.
`422 Unprocessable`	Planning failure — locations unreachable or battery constraints unmet.
`500 Server Error`	Backend failure (e.g., routing engine unreachable).

Polyline Encoding: Returns encoded polylines (precision 5). Clients must decode to [[lat, lng], ...].
Station Search: Uses BBox region search. Strict candidates within corridorM, Backup candidates up to ~20km.
Instruction Signs: 0 = Continue, -2 = Left, 2 = Right, 4 = Arrive, 5 = Charge.

18

List Geofences

Retrieve a list of all active geofences owned by the authorized user.

GET /api/v2/map/geofence/v2/

Example Response

[
    {
        "_id": "64b58e74f1b2c8a910ab3cd4",
        "name": "Headquarters Delivery Zone",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [ [100.5, 13.7], [100.6, 13.7], [100.6, 13.8], [100.5, 13.8], [100.5, 13.7] ]
            ]
        },
        "properties": {
            "type": "restricted",
            "max_speed": 50
        },
        "description": "Main restricted zone",
        "isActive": true,
        "owner": "user_id_123",
        "createdAt": "2026-03-05T06:00:00.000Z",
        "updatedAt": "2026-03-05T06:00:00.000Z"
    }
]

19

Create Geofence

Create a new custom geofence zone using GeoJSON geometry.

POST /api/v2/map/geofence/v2/

JSON Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Name of the geofence zone.
`geometry`	`object`	Yes	Valid GeoJSON Geometry Object (e.g. Polygon, MultiPolygon).
`properties`	`object`	No	Custom arbitrary properties associated with this zone.
`description`	`string`	No	Note or long description for this geofence.

Example Request

{
  "name": "Warehouse A",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [ [100.5, 13.7], [100.6, 13.7], [100.6, 13.8], [100.5, 13.8], [100.5, 13.7] ]
    ]
  },
  "properties": { "color": "blue" }
}

20

Check Zone

Test whether a given coordinate point (lat/lng) falls inside any of your active geofences.

GET /api/v2/map/geofence/v2/checkzone

Query Parameters

Parameter	Type	Required	Description
`lat`	`number`	Yes	Target latitude to check.
`lng`	`number`	Yes	Target longitude to check.

Example Response

Returns an array indicating whether the point is "in" or "out" of the user's zones.

[
    {
        "zone_id": "64b58e74f1b2c8a910ab3cd4",
        "zone_name": "Headquarters Delivery Zone",
        "zone_status": "in",
        "properties": { "type": "restricted", "max_speed": 50 }
    }
]

21

Get Geofence

Retrieve a specific geofence by its internal _id.

GET /api/v2/map/geofence/v2/:id

Example Response

[
    {
        "_id": "64b58e74f1b2c8a910ab3cd4",
        "name": "Headquarters Delivery Zone",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [ [100.5, 13.7], [100.6, 13.7], [100.6, 13.8], [100.5, 13.8], [100.5, 13.7] ]
            ]
        },
        "properties": {
            "type": "restricted",
            "max_speed": 50
        },
        "description": "Main restricted zone",
        "isActive": true,
        "owner": "user_id_123",
        "createdAt": "2026-03-05T06:00:00.000Z",
        "updatedAt": "2026-03-05T06:00:00.000Z"
    }
]

22

Update Geofence

Update properties, geometry, or status of an existing geofence.

PUT /api/v2/map/geofence/v2/:id

JSON Request Body (Optional Fields)

Provide only the fields you wish to update.

{
  "name": "Updated Warehouse A",
  "isActive": false
}

23

Delete Geofence

Permanently completely delete a geofence.

DEL /api/v2/map/geofence/v2/:id

Example Response

{
  "success": true
}

Powermap API Documentation

Authentication

Server Information

Parameters

Example Response

Geocode

Query Parameters

Example Request

Example Response

Search (Address & POI)

Query Parameters

Example Request

Example Response

Source Object (_source)

Nearby Search

Query Parameters

Example Request

Example Response

Suggestions (Autocomplete)

Query Parameters

Example Request

Example Response

Road Search

Query Parameters

Example Request

Example Response

Road Suggest

Query Parameters

Example Request

Example Response

Category Search

Category APIs Overview

Example Response (Subcategory)

Query Parameters

Example Request

Example Response

Category Major

Example Response

Category Sub

Example Response

Reverse Geocoding

Query Parameters

Example Request

Example Response

Speed Limit

Query Parameters

Example Request

Example Response

Routing

Path Parameters

Query Parameters (all optional)

Example Request

Example Response

Error Responses

Routing (Standard)

Request Body Parameters

Example Request

Example Response

Error Responses

Vehicle Routing Problem (VRP)

Request Body (VROOM Format)

Example Request

Response Body (VROOM Format)

Example Response

Error Responses

Route Optimize (Multi-Stop)

Request Body

Stops Object

Example Request

Response Body

Steps Object

Example Response

Error Responses

Route Navigate (Turn-by-Turn)

Request Body

Example Request

Response Body

Example Response (Condensed)

Leg Steps Object

Error Responses

Source Object (`_source`)

Route Object (`route.paths[0]`)