VectorMaps API
Generate preview and production map files programmatically for UK, Ireland, and worldwide map modes from your own applications.
Why it works
The API uses the same rendering pipeline as the browser tool, so outputs stay consistent across manual and automated workflows.
- Asynchronous job queue designed for reliable background processing.
- Supports styled vector maps plus GIS package delivery modes.
- Coverage-aware mode validation for UK-only, Ireland-only and worldwide maps.
How it works
Post a JSON render request, receive a job id, then poll the status endpoint until the result is complete and file URLs are returned.
Quick Start
All API requests are JSON POSTs to /projects/dev_project/api_render.php with your API key in the header X-API-Key.
curl -X POST https://vectormaps.uk/projects/dev_project/api_render.php \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"action": "preview_svg",
"xmin": -1.204,
"ymin": 54.11,
"xmax": -1.124,
"ymax": 54.18,
"mode": "zoomstack_default",
"paper_size": "A4"
}'
The API is asynchronous. You will receive a job id, then poll the status endpoint.
Authentication
Use your API key in the request header:
X-API-Key: YOUR_API_KEY
You can also pass it in the JSON payload as api_key for testing, but headers are recommended.
Actions
| Action | Result | Output |
|---|---|---|
| preview_svg | Preview SVG with sample watermark | SVG file URL |
| preview_pdf | Preview PDF with panel + sample watermark | PDF file URL |
| production_svg | Final production SVG (no watermark) | SVG file URL |
| production_pdf | Final production PDF (no watermark) | PDF file URL |
| production_package | Final packaged outputs (mode-dependent) | ZIP + file URLs |
GIS worldwide mode: production_package returns
GPKG + GeoJSON (no production SVG/PDF), and
production_svg/production_pdf are not valid for that mode.
Asynchronous Workflow
Requests are queued and processed by the worker. The API returns a job_id to poll:
GET https://vectormaps.uk/projects/dev_project/api_job_status.php?job_id=123
X-API-Key: YOUR_API_KEY
Response includes status: queued, running, done, failed.
Required Parameters
| Field | Type | Description |
|---|---|---|
| action | string | One of the supported actions. |
| xmin | number | West bound (EPSG:4326 longitude). |
| ymin | number | South bound. |
| xmax | number | East bound. |
| ymax | number | North bound. |
Optional Parameters
| Field | Type | Description |
|---|---|---|
| mode | string | Map style / project. Default: standard. |
| paper_size | string | A0–A10. Default: A4. |
| layout_name | string | web_export or empty. |
| show_compass | bool | Default: true. |
| show_scale | bool | Default: true. |
| custom_fit | bool | Crop to area. |
| scale | number | Overrides export scale. |
| overlay_layers | array | e.g. ["postcode_sectors"]. |
| overlay_boundary_color | string | Hex color. |
| overlay_boundary_width | number | Boundary line width. |
| overlay_label_scale | number | Percent scale for labels. |
| show_frame | bool | Enable border frame. |
| frame_color | string | Frame hex color. |
| show_postcode | bool | Enable postcode overlay. |
| postcode_sector | string | e.g. "YO18 7" |
| postcode_type | string | district / sector |
| postcode_color | string | Hex color for postcode boundary. |
| layers | array | Optional layer list to include. |
| colour_map | object | Map of color replacements. |
| map_id | string | Optional public id for file naming. |
| price_pence | int | Preview PDF price label. |
| buy_url | string | Preview PDF purchase URL. |
Allowed Values
Mode
- standard
- mono
- zoomstack_default
- zoomstack_road
- zoomstack_road_mm
- zoomstack_outdoor
- zoomstack_night
- zoomstack_light2
- zoomstack_greyscale
- zoomstack_deuteranopia
- zoomstack_tripitania
- overture_europe
- overture_worldwide_mono
- gis_worldwide
- ireland_map
- os_tourism
- os_vector
- os_open_light
- os_open_natural
- boundaryline
Paper Size
A0–A10
Layout
web_export or empty
Postcode Type
district or sector
Geographic Coverage Rules
| Mode Group | Modes | Selection Coverage |
|---|---|---|
| UK-only | standard, mono, zoomstack_default, zoomstack_road, zoomstack_road_mm, zoomstack_outdoor, zoomstack_night, zoomstack_light2, zoomstack_greyscale, zoomstack_deuteranopia, zoomstack_tripitania, os_tourism, os_vector, os_open_light, os_open_natural, boundaryline | Bounds must overlap England, Scotland, or Wales. |
| Ireland-only | ireland_map | Bounds must overlap Ireland. |
| Worldwide (Overture) | overture_europe, overture_worldwide_mono, gis_worldwide | No geographic restriction (global coverage). |
Responses
Queued response:
{
"ok": true,
"action": "preview_svg",
"message": "Job queued.",
"job_id": 123,
"status_url": "/projects/dev_project/api_job_status.php?job_id=123"
}
Completed response (polling job status):
{
"ok": true,
"job_id": 123,
"status": "done",
"result": {
"ok": true,
"action": "preview_svg",
"message": "Preview SVG created.",
"file": "/projects/dev_project/svg_preview_files/preview_123_456.svg",
"file_url": "https://vectormaps.uk/projects/dev_project/svg_preview_files/preview_123_456.svg"
}
}
GIS worldwide package response (inside result):
{
"ok": true,
"action": "production_package",
"file": "/projects/dev_project/completed_maps/map_123.zip",
"gpkg_file": "/projects/dev_project/completed_maps/map_123.gpkg",
"geojson_file": "/projects/dev_project/completed_maps/map_123.geojson",
"pdf_file": null,
"svg_file": null
}
Quotas
Each API key can have per-action quotas. When exceeded, the API responds:
{
"ok": false,
"error": "Quota exceeded. Please try again later.",
"retry_after": 86400
}
Worker (Async Processing)
Run the worker manually or via cron:
https://vectormaps.uk/projects/dev_project/api_worker.php?limit=3
Optional worker auth: create api_config.php with a worker_key
and call api_worker.php?key=YOUR_SECRET.
JavaScript Example
const res = await fetch("https://vectormaps.uk/projects/dev_project/api_render.php", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
},
body: JSON.stringify({
action: "preview_pdf",
xmin: -1.204,
ymin: 54.11,
xmax: -1.124,
ymax: 54.18,
mode: "zoomstack_default"
})
});
const data = await res.json();
Python Example
import requests
payload = {
"action": "production_package",
"xmin": -1.204,
"ymin": 54.11,
"xmax": -1.124,
"ymax": 54.18,
"mode": "zoomstack_default"
}
res = requests.post(
"https://vectormaps.uk/projects/dev_project/api_render.php",
json=payload,
headers={"X-API-Key": "YOUR_API_KEY"}
)
print(res.json())