Call MapScale from any server language over HTTPS with JSON and GeoJSON responses.

What you’ll achieve

Use the REST API for search, routing, matrices, static images and server-side workflows.

Base URL and authentication

Send production traffic to https://api.mapscale.io. Protected endpoints accept a key in X-MapScale-Key.

Edit the inputs, send a real request, and inspect the live response.

Editable inputs

qrequiredstringmin length 1

langoptionalstring17 options

limitoptionalintegermin 1max 50

bboxoptionalstring

proximityoptionalstring

curl \
  -H "X-MapScale-Key: $MAPSCALE_API_KEY" \
  "https://api.mapscale.io/v1/geocode?q=Siam+Paragon&lang=th&limit=5"

Default response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "place_bangkok_123",
      "text": "Siam Paragon",
      "place_name": "Siam Paragon, Pathum Wan, Bangkok",
      "geometry": {
        "type": "Point",
        "coordinates": [
          100.5348,
          13.7466
        ]
      },
      "properties": {
        "latitude": 13.7466,
        "longitude": 100.5348,
        "formattedAddress": "Siam Paragon, Pathum Wan, Bangkok 10330, Thailand",
        "street": "Rama I Road",
        "neighborhood": "Siam",
        "subdistrict": "Pathum Wan",
        "district": "Pathum Wan",
        "province": "Bangkok",
        "postalCode": "10330",
        "country": "Thailand"
      }
    }
  ]
}

Read responses

Successful JSON responses use standard HTTP status codes. Search endpoints return GeoJSON-like features. Image and tile endpoints return binary content with an appropriate Content-Type.

Handle errors

Treat 400 as an input problem, 401 as missing authentication, 403 as a restriction problem, 429 as a signal to back off, and 5xx as retryable only with bounded exponential backoff.

Example 2 — a retryable upstream failure

When the geocoding backend is unreachable, the API answers with a 503 and the same {error:{code,message}} shape every endpoint uses — never a bare 500 or an HTML error page.

Edit the inputs, send a real request, and inspect the live response.

Editable inputs

qrequiredstringmin length 1

langoptionalstring17 options

limitoptionalintegermin 1max 50

bboxoptionalstring

proximityoptionalstring

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

Default response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "place_bangkok_123",
      "text": "Siam Paragon",
      "place_name": "Siam Paragon, Pathum Wan, Bangkok",
      "geometry": {
        "type": "Point",
        "coordinates": [
          100.5348,
          13.7466
        ]
      },
      "properties": {
        "latitude": 13.7466,
        "longitude": 100.5348,
        "formattedAddress": "Siam Paragon, Pathum Wan, Bangkok 10330, Thailand",
        "street": "Rama I Road",
        "neighborhood": "Siam",
        "subdistrict": "Pathum Wan",
        "district": "Pathum Wan",
        "province": "Bangkok",
        "postalCode": "10330",
        "country": "Thailand"
      }
    }
  ]
}

Next stepBrowse the API reference →

REST API integration

Base URL and authentication

Sign in or create an account

Editable inputs

Read responses

Handle errors

Example 2 — a retryable upstream failure

Sign in or create an account

Editable inputs

On this page