MapScale API

Contract-derived reference for auth, parameters, response codes, and curl examples.

Autocomplete

Session-priced place suggestions for search boxes and map pickers.

GET/v1/autocomplete

Autocomplete a place or address query

Autocomplete suggestions. Backed by Photon (v1) -> ES phonetic (v1.5). Billing SKU: autocomplete (per session, not per keystroke).

Public endpoint3 response codes6 parameters

Name	In	Type	Required
`q`	query	string	yes
`lang`	query	string	no
`session_token`	query	string	no
`bbox`	query	string	no
`proximity`	query	string	no
`types`	query	string	no

200400404

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/autocomplete?q=13.7563&lang=example&session_token=example"

Geocoding

Forward, reverse, place detail and Thai administrative lookup endpoints.

GET/v1/admin-areas/reverse

Reverse lookup Thai administrative areas

Point-in-polygon admin-area lookup over geography.* (PostGIS ST_Contains). Billing SKU: geocode.

Public endpoint3 response codes2 parameters

Name	In	Type	Required
`point`	query	string	yes
`lang`	query	string	no

200400404

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/admin-areas/reverse?point=13.7563&lang=example"

GET/v1/geocode

Geocode a place or address query

Forward geocode. Backed by Photon /api. Billing SKU: geocode.

Public endpoint3 response codes6 parameters

Name	In	Type	Required
`q`	query	string	yes
`lang`	query	string	no
`limit`	query	integer	no
`bbox`	query	string	no
`proximity`	query	string	no
`country`	query	string	no

200400404

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/geocode?q=13.7563&lang=example&limit=example"

GET/v1/place/{id}

Fetch a place by ID

Place details, by a photon:... id (from /v1/geocode or /v1/autocomplete) or a mapscale places.places uuid. Billing SKU: geocode (free if same session).

Public endpoint3 response codes2 parameters

Name	In	Type	Required
`id`	path	string	yes
`lang`	query	string	no

200400404

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/place/example-id?lang=example"

GET/v1/reverse

Reverse geocode coordinates

Reverse geocode. Backed by Photon /reverse, enriched with PostGIS admin-area names. Billing SKU: geocode.

Public endpoint3 response codes3 parameters

Name	In	Type	Required
`point`	query	string	yes
`lang`	query	string	no
`zoom`	query	integer	no

200400404

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/reverse?point=13.7563&lang=example&zoom=example"

Routes

Directions and isochrones powered by Thailand-aware routing data.

GET/v1/isochrone

Build a travel-time isochrone

Time/distance reachability polygons around a point. Backed by Valhalla /isochrone. Billing SKU: routing.

Public endpoint3 response codes3 parameters

Name	In	Type	Required
`point`	query	string	yes
`profile`	query	string	no
`contours`	query	string	yes

200400502

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/isochrone?point=13.7563&profile=example&contours=100.5018"

GET/v1/route

Calculate a route with query parameters

Route between 2+ waypoints. Backed by Valhalla /route. Billing SKU: routing.

Public endpoint3 response codes4 parameters

Name	In	Type	Required
`coordinates`	query	string	yes
`profile`	query	string	no
`alternatives`	query	boolean	no
`lang`	query	string	no

200400502

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/route?coordinates=13.7563&profile=example&alternatives=example"

POST/v1/route

Calculate a route with a JSON body

Route between 2+ waypoints. Backed by Valhalla /route. Billing SKU: routing.

Public endpoint3 response codes0 parameters

Request bodyOptional application/json

200400502

curl

curl \
  -X POST \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/route"

Matrix

Travel-time and distance matrices for dispatch, ranking and coverage checks.

POST/v1/matrix

Calculate a route matrix

Travel-time/distance matrix, capped at 25x25 in v1. Backed by Valhalla /sources_to_targets. Billing SKU: matrix (per element).

Public endpoint3 response codes0 parameters

Request bodyOptional application/json

200400502

curl

curl \
  -X POST \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/matrix"

Tiles

Vector tiles for interactive MapLibre maps.

GET/tiles/v1/{tileset}/{z}/{x}/{yFile}

Fetch a vector tile

Public endpoint3 response codes4 parameters

Name	In	Type	Required
`tileset`	path	string	yes
`z`	path	integer	no
`x`	path	integer	no
`yFile`	path	string	yes

200404503

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/tiles/v1/example-tileset/1/1/example.json"

Static maps

Server-rendered map images for previews, emails and sharing.

GET/v1/static/{lonLatZoom}/{sizeFile}

Render a static map image

Public endpoint5 response codes7 parameters

Name	In	Type	Required
`lonLatZoom`	path	string	yes
`sizeFile`	path	string	yes
`styleId`	query	string	no
`lang`	query	string	no
`accent`	query	string	no
`markers`	query	string	no
`path`	query	string	no

200400404502503

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/static/example-lonLatZoom/example.json?styleId=example&lang=example&accent=example"

Styles

MapLibre style documents that reference MapScale tiles, glyphs and sprites.

GET/styles/v1/{styleId}

Fetch a MapLibre style

Public endpoint1 response codes4 parameters

Name	In	Type	Required
`styleId`	path	string	yes
`lang`	query	string	no
`accent`	query	string	no
`hide`	query	string[] \| string	no

200

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/styles/v1/example-styleId?lang=example&accent=example&hide=example"

Glyphs and sprites

Font ranges and sprite assets consumed by MapLibre styles.

GET/fonts/v1/{fontstack}/{rangeFile}

Fetch a glyph range

Public endpoint2 response codes2 parameters

Name	In	Type	Required
`fontstack`	path	string	yes
`rangeFile`	path	string	yes

302503

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/fonts/v1/example-fontstack/0-255.pbf"

GET/sprites/v1/{styleId}/{filename}

Fetch a map sprite asset

Public endpoint2 response codes2 parameters

Name	In	Type	Required
`styleId`	path	string	yes
`filename`	path	string	yes

302503

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/sprites/v1/example-styleId/example.json"

Health and contract

Public operational checks and the OpenAPI document.

GET/v1/health

Liveness probe

Public endpoint1 response codes0 parameters

200

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/health"

GET/v1/status

Check dependency status

Public endpoint1 response codes0 parameters

200

curl

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/status"

POST/v1/trial-key

Create a limited publishable trial key

Creates a trial account and a browser-safe `pk_test_*` key for client-side MapScale integration. The key is restricted to tiles, autocomplete and static maps.

Public endpoint3 response codes0 parameters

Request bodyRequired application/json

201400429

curl

curl \
  -X POST \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/trial-key"

MapScale API

Autocomplete

Autocomplete a place or address query

Geocoding

Reverse lookup Thai administrative areas

Geocode a place or address query

Fetch a place by ID

Reverse geocode coordinates

Routes

Build a travel-time isochrone

Calculate a route with query parameters

Calculate a route with a JSON body

Matrix

Calculate a route matrix

Tiles

Fetch a vector tile

Static maps

Render a static map image

Styles

Fetch a MapLibre style

Glyphs and sprites

Fetch a glyph range

Fetch a map sprite asset

Health and contract

Liveness probe

Check dependency status

Create a limited publishable trial key

On this page