PlanningMapsUK / API reference

Maps API
reference.

Quote a location. Generate a map. Download PNG, PDF, DXF or DWG.

Start here

Authentication

Send a bearer API key with every request. Create test and live keys in your account.

Keep keys on your server. Never put them in browser code, URLs or source control. The secret is shown once.

Authorization required header: Bearer YOUR_API_KEY
Content-Type POST requests: application/json. Bodies must be JSON objects, no larger than 8 KB.

Live generation requires an approved account, an active subscription and sufficient prepaid balance. API keys cannot top up or change billing.

1curl 'https://planningmapsuk.co.uk/api/v1/catalog' \
2  -H "Authorization: Bearer $PMUK_API_KEY"

Authenticated catalogue request

Test your integration

Make your first test call

Create a pmuk_test_… key in your account and set PMUK_API_KEY on your server. Test calls are free and return the Cambridge test files. No credits or top-ups are needed.

Location fixed coordinates: latitude: 52.20425, longitude: 0.11535
Area fixed: hectares: 5.0625
Map and layers fixed: map_type: mastermap, layers: []
Output your choice: PNG, PDF, DXF or DWG. For CAD, send file_type: cad and file_format: dxf or dwg.

The sandbox accepts this location and area only; other values return 422 sandbox_parameters. Both test and live keys use https://planningmapsuk.co.uk/api/v1; the key selects the environment. Use a test key for sandbox calls, then a live key for paid integration.

1export PMUK_API_KEY="YOUR_TEST_API_KEY"
2case "$PMUK_API_KEY" in
3  pmuk_test_*) ;;
4  *) echo "Use a test key for this quickstart." >&2; exit 1 ;;
5esac

Set your test key

1curl -X POST 'https://planningmapsuk.co.uk/api/v1/quotes' \
2  -H "Authorization: Bearer $PMUK_API_KEY" \
3  -H "Content-Type: application/json" \
4  --data '{
5  "location": {
6    "latitude": 52.20425,
7    "longitude": 0.11535
8  },
9  "map_type": "mastermap",
10  "hectares": 5.0625,
11  "file_type": "cad",
12  "file_format": "dwg",
13  "layers": []
14}'

Test request · POST /quotes

Use the returned quote id in POST /maps, then poll GET /maps/{id} for the download. Reuse the same Idempotency-Key when retrying a submission.

POST/quotes

Request a quote

Resolve the location and get a fixed price before ordering. Quotes last 15 minutes and snapshot the dataset, area, format and price.

locationobject · required: Exactly one of the location representations below.
map_typestring · required: Explicit source dataset. Check catalogue enablement first.
mastermapopendata
hectaresnumber · required: 0.1–25 inclusive. Total square area, not a radius or a property boundary.
file_typestring · required: Choose an image, PDF or CAD drawing.
pngpdfcad
file_formatstring · required for CAD: Required for CAD. Omit entirely for PNG/PDF. OpenData CAD is unsupported.
dxfdwg
layersarray · optional: Omit or send an empty array. Nonempty lists are currently rejected.
[]

Location options

Send exactly one representation inside location.

addressstring · 8–250 characters: Complete address including postcode. Exact full-address matching; no wildcards. Ambiguous matches return candidates—resubmit their UPRN.
uprnstring · 1–12 digits: Keep it as a string, including any leading zeros.
latitude + longitudetwo numbers: WGS84 decimal degrees. Latitude −90 to 90; longitude −180 to 180. Both are required together. The whole map must also fall within dataset coverage.

Hectares are the total area of a north-aligned square in British National Grid. Side length = √(hectares × 10,000) metres. No property boundary is inferred.

Example output

1curl -X POST 'https://planningmapsuk.co.uk/api/v1/quotes' \
2  -H "Authorization: Bearer $PMUK_API_KEY" \
3  -H "Content-Type: application/json" \
4  --data '{
5  "location": {
6    "latitude": 52.20425,
7    "longitude": 0.11535
8  },
9  "map_type": "mastermap",
10  "hectares": 5.0625,
11  "file_type": "cad",
12  "file_format": "dwg",
13  "layers": []
14}'

Create a quote · POST /quotes

1{
2  "id": "c01c12d1-e352-4c83-95d9-2ce4b117251e",
3  "location": {
4    "latitude": 52.20425,
5    "longitude": 0.11535,
6    "address": "King's College and River Cam, Cambridge"
7  },
8  "coverage": {
9    "bbox": [
10      544536.7185758532,
11      258219.288021054,
12      544761.7185758532,
13      258444.288021054
14    ],
15    "crs": "EPSG:27700",
16    "hectares": 5.0625
17  },
18  "map_type": "mastermap",
19  "format": "dwg",
20  "price_pence": 12995,
21  "currency": "GBP",
22  "expires_at": "2030-01-01T12:15:00Z"
23}

200 OK · quote response

Use the quote ID and expiry returned by your test call.

POST/maps

Generate a map

Accept a quote and queue generation. The quoted amount is reserved immediately and captured only after the requested file is stored successfully.

quote_idUUID · required body field: The unexpired quote ID. This is the only accepted body field.
Idempotency-Keyrequired header · 1–128 characters: Printable ASCII without spaces. Use a stable reference for this order and reuse it when retrying the same request.

Each quote creates at most one job. Replays return that job. Reusing an idempotency key for another quote returns 409 idempotency_conflict.

A successful submission returns 202 and Retry-After: 5. Poll the returned job ID rather than resubmitting with a new key.

1curl -X POST 'https://planningmapsuk.co.uk/api/v1/maps' \
2  -H "Authorization: Bearer $PMUK_API_KEY" \
3  -H "Content-Type: application/json" \
4  -H "Idempotency-Key: project-123-map-1" \
5  --data '{
6  "quote_id": "c01c12d1-e352-4c83-95d9-2ce4b117251e"
7}'

Submit a quoted map

1{
2  "id": "1e2a3333-4444-4555-8666-777777777777",
3  "status": "queued"
4}

202 Accepted · Retry-After: 5

GET/maps/{id}

Retrieve a map

Read a job’s status and download the completed file. The job must belong to your account and key environment.

idUUID · required path parameter: The job ID returned by POST /maps.

queuedFunds reserved; waiting for a worker.
processingThe requested file is being generated.
completedFile ready; reservation captured.
failedGeneration unsuccessful; reservation released.

Queued and processing responses include Retry-After: 5. Failed jobs release the reservation; request a new quote to try again.

Signed links last 15 minutes. Fetch this endpoint again for a fresh link without paying again. Files are retained for 30 days; afterwards the response contains download_expired: true.

1curl 'https://planningmapsuk.co.uk/api/v1/maps/1e2a3333-4444-4555-8666-777777777777' \
2  -H "Authorization: Bearer $PMUK_API_KEY"

Poll a job

1{
2  "id": "1e2a3333-4444-4555-8666-777777777777",
3  "currency": "GBP",
4  "created_at": "2030-01-01T12:00:00Z",
5  "status": "queued",
6  "charged_pence": 0
7}

200 OK · job response by status

Download links expire after 15 minutes and work directly in a browser. Use the returned URL unchanged; retrieve the map again for a fresh link.

GET/catalog

Read the catalogue

Check available products, output formats, price bands and account-wide limits. This endpoint has no parameters.

Only order a product when enabled is true. OpenData is OS Open Zoomstack, a contextual map with less detail than MasterMap. OpenData CAD is unsupported.

Output compatibility
Dataset	PNG	PDF	DXF / DWG
MasterMap Topography	Yes	Yes	Yes
Open Zoomstack	Yes	Yes	No

Prices use integer GBP pence and the smallest published band covering your area. PNG uses PDF prices. A quote fixes the price even if the catalogue changes.

1curl 'https://planningmapsuk.co.uk/api/v1/catalog' \
2  -H "Authorization: Bearer $PMUK_API_KEY"

Read products and prices

1{
2  "currency": "GBP",
3  "prices_include_vat": true,
4  "subscription_pence": 5000,
5  "limits": {
6    "min_hectares": 0.1,
7    "max_hectares": 25,
8    "quotes_per_minute": 30,
9    "submissions_per_minute": 10,
10    "reads_per_minute": 120,
11    "outstanding_jobs": 2
12  },
13  "map_types": [
14    {
15      "id": "mastermap",
16      "name": "OS MasterMap Topography",
17      "formats": [
18        "png",
19        "pdf",
20        "dxf",
21        "dwg"
22      ],
23      "enabled": true,
24      "layers": []
25    },
26    {
27      "id": "opendata",
28      "name": "OS Open Zoomstack",
29      "formats": [
30        "png",
31        "pdf"
32      ],
33      "enabled": false,
34      "layers": []
35    }
36  ],
37  "prices": {
38    "png_pdf": [
39      {
40        "up_to_hectares": 0.12,
41        "price_pence": 795
42      },
43      {
44        "up_to_hectares": 0.81,
45        "price_pence": 1495
46      },
47      {
48        "up_to_hectares": 2,
49        "price_pence": 2050
50      },
51      {
52        "up_to_hectares": 3,
53        "price_pence": 2795
54      },
55      {
56        "up_to_hectares": 4,
57        "price_pence": 3395
58      },
59      {
60        "up_to_hectares": 5.1,
61        "price_pence": 3995
62      },
63      {
64        "up_to_hectares": 10,
65        "price_pence": 5995
66      },
67      {
68        "up_to_hectares": 15,
69        "price_pence": 6995
70      },
71      {
72        "up_to_hectares": 20,
73        "price_pence": 7995
74      },
75      {
76        "up_to_hectares": 50,
77        "price_pence": 11495
78      }
79    ],
80    "cad": [
81      {
82        "up_to_hectares": 0.1,
83        "price_pence": 1495
84      },
85      {
86        "up_to_hectares": 0.25,
87        "price_pence": 2295
88      },
89      {
90        "up_to_hectares": 0.81,
91        "price_pence": 2995
92      },
93      {
94        "up_to_hectares": 1.7,
95        "price_pence": 3995
96      },
97      {
98        "up_to_hectares": 3,
99        "price_pence": 5995
100      },
101      {
102        "up_to_hectares": 5,
103        "price_pence": 6795
104      },
105      {
106        "up_to_hectares": 10,
107        "price_pence": 12995
108      },
109      {
110        "up_to_hectares": 20,
111        "price_pence": 23595
112      },
113      {
114        "up_to_hectares": 25,
115        "price_pence": 23995
116      }
117    ]
118  }
119}

200 OK · catalogue structure

Sandbox catalogue shown. Live product enablement depends on your activated datasets.

GET/balance

Check the balance

No parameters. The balance is scoped to your account and the key’s test or live environment.

available_penceinteger: Spendable funds after reservations.
reserved_penceinteger: Funds held for outstanding jobs; unavailable for another order.
currency / environmentstrings: GBP and either test or live.

Top-ups, refunds and subscription changes require account login. An API key grants no financial-management access.

1curl 'https://planningmapsuk.co.uk/api/v1/balance' \
2  -H "Authorization: Bearer $PMUK_API_KEY"

Read available and reserved funds

1{
2  "available_pence": 0,
3  "reserved_pence": 0,
4  "currency": "GBP",
5  "environment": "live"
6}

200 OK · production balance

GET/maps

List map history

Returns up to 50 jobs, newest first. History includes location, area, output format, status, charge and creation time.

offsetinteger · optional query parameter: Default 0. Accepted range 0–10000. Use the returned next_offset for the next page; null means there are no further pages indicated.

History does not include download links. Retrieve a completed job by ID to get its current signed URL. charged_pence is zero until completion.

1curl 'https://planningmapsuk.co.uk/api/v1/maps?offset=0' \
2  -H "Authorization: Bearer $PMUK_API_KEY"

First history page

1{
2  "maps": [
3    {
4      "id": "1e2a3333-4444-4555-8666-777777777777",
5      "status": "completed",
6      "location": {
7        "latitude": 52.20425,
8        "longitude": 0.11535,
9        "address": "King's College and River Cam, Cambridge"
10      },
11      "hectares": 5.0625,
12      "format": "dwg",
13      "charged_pence": 12995,
14      "created_at": "2030-01-01T12:00:00Z"
15    }
16  ],
17  "next_offset": null
18}

200 OK · paginated history

Output details

PNG / PDF

PNG: 2,048 × 2,048 pixels. PDF: A4 portrait, square map frame, calculated scale, scale bar, north arrow and attribution.

DXF / DWG

British National Grid coordinates in metres. The requested CAD format must be delivered; DXF is not a substitute for a DWG order.

Current API requests accept layers: [] only. ArborLayer, imagery and terrain selections in the landing-page explorer are examples, not enabled API exports.

Coverage is checked against the dataset footprint, including holes. These files do not infer ownership, draw a property boundary or establish planning-submission suitability. Keep attribution and add annotations required for your project.

Inspect the files

Cambridge samples

Download PNG, PDF, DXF and DWG reference files.

Watermarked Cambridge colour mapping sample

Centre WGS84: 52.20425, 0.11535
Coverage: 225 × 225 metres · 5.0625 ha (published as 5.1 ha).

PNGcambridge-example.png811 KB · OS MasterMap Topography CAD preview PDFcambridge-example.pdf2.0 MB · Storefront NGD vector rendering DXFcambridge-example.dxf593 KB · OS MasterMap Topography DWGcambridge-example.dwg139 KB · OS MasterMap Topography

1{
2  "location": {
3    "latitude": 52.20425,
4    "longitude": 0.11535
5  },
6  "hectares": 5.0625,
7  "coverage": {
8    "bbox": [
9      544536.7185758532,
10      258219.288021054,
11      544761.7185758532,
12      258444.288021054
13    ],
14    "crs": "EPSG:27700"
15  }
16}

Cambridge sample location and extent

Errors and retries

Errors contain code, message and request_id. Useful validation details may be included. Share the request ID with support, never your key.

400 / 422Invalid input or coverage: Correct fields or choose a covered location. Unknown fields and unsupported combinations are rejected.
401Invalid credentials: Check the bearer header and whether the key was revoked.
402Insufficient balance: Top up in your account before submitting.
403Access unavailable: Check approval, subscription and wallet status.
404Not found: Check the quote/job ID and test/live environment. Address lookup may also return location_not_found.
409Quote or idempotency conflict: Expired quote: request a new one. Idempotency conflict: check the order association. Billing busy: retry shortly with the same key.
413 / 415Body too large or wrong content type: Keep JSON under 8 KB and send Content-Type: application/json.
429Rate, job or spend limit: Respect Retry-After. Wait for jobs or review the daily cap before ordering again.
500 / 503Temporary failure: Retry with backoff and the same submission key. Keep the request ID for support.

For a network failure during submission, retry the same quote and idempotency key. For transient server failures, use bounded retries with backoff. Do not automatically retry invalid input or a failed generation as a new paid order.

1{
2  "code": "insufficient_balance",
3  "message": "Top up your balance before generating this map.",
4  "request_id": "51e84591-20d4-447a-9ef8-36c66ee69684"
5}

402 Payment Required

1{
2  "code": "ambiguous_address",
3  "message": "Choose a UPRN and request another quote.",
4  "request_id": "51e84591-20d4-447a-9ef8-36c66ee69684",
5  "details": {
6    "candidates": [
7      {
8        "uprn": "100000000001",
9        "address": "King's College and River Cam, Cambridge"
10      }
11    ]
12  }
13}

422 · ambiguous address candidates

Limits

30 / minQuote requests

10 / minGeneration submissions

120 / minRead requests

2 jobsOutstanding per account

Limits are shared across keys for each account and environment. Reservations count towards the default £250 daily generation cap. Two jobs may be queued or processing at once. IP-based abuse protection also applies.

A 429 response includes Retry-After: 60. Respect it, then check the error code: outstanding-job and spend limits need capacity or allowance, not repeated submissions.

API use and billing

Terms version 2026-09-28. Approved UK businesses may produce their own project and client deliverables. Public resale, embedded ordering, bulk extraction and credential sharing are not permitted. Retain attribution and follow the product licence supplied at activation.

API access is £50 per month, with no included map credit. Maps use a separate prepaid balance. Top-ups are £20–£1,000; unspent funds carry forward. Cancellation takes effect at the end of the paid period. Contact support for refunds of unused, unreserved balance to the original payment method.

New generation requires an active subscription. Existing downloads remain available within their 30-day retention period. Store completed files in your own system.

Download the OpenAPI specification