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 api_render.php with your API key in the header X-API-Key. Replace the example host/path with your own dev machine URL.
The API is asynchronous. You will receive a job id, then poll the status endpoint.
Returned file and status paths are built from public_base_path in api_config.php.
Authentication
Use your API key in the request header:
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 sample watermark; copyright label retained) | SVG file URL |
| production_pdf | Final production PDF (no sample watermark; copyright label retained) | PDF file URL |
| production_package | Final packaged outputs (mode-dependent) | ZIP + file URLs |
Asynchronous Workflow
Requests are queued and processed by the worker. The API returns a job_id to poll:
Response includes status: queued, running, done, failed.
Required Parameters
Bounds are supplied as EPSG:4326 longitude/latitude values. Use west/south/east/north ordering.
| 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
- master_map_data
- master_map_data_22
- 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, master_map_data, master_map_data_22, 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). |
| Minimum area | os_tourism, os_vector | os_tourism requires at least 20,000 hectares. os_vector requires at least 1,000 hectares. |
Responses
Queued response:
The status_url prefix follows public_base_path.
Completed response (polling job status):
GIS worldwide package response (inside result):
Quotas
Each API key can have per-action quotas. When exceeded, the API responds:
Worker (Async Processing)
Run the worker manually or via cron:
If jobs stay as queued, the worker is not running or the worker key does not match.
Dev Machine Setup
The render API uses local filesystem paths and command-line render scripts. On a second dev computer, copy api_config.example.php to api_config.php and adjust paths if needed.
- project_root must point at the dev_project folder containing render_svg.py, render_pdf.py, qgz_files, and gpkg_files.
- public_base_path must match the URL path used by the web server.
- python_bin should be python3 on Linux or python on Windows if that is how Python is installed.
- The folders svg_preview_files, pdf_preview_files, completed_maps, and gpkg_files/*_cache must be writable by PHP/the worker.
- QGIS/GDAL command-line dependencies used by the render scripts must be installed and available to the same user running the worker.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Job stays queued | Run api_worker.php; check worker_key. |
| Render failed | Check project_root, writable output folders, Python, QGIS and GDAL availability. |
| Output URL path is wrong | Set public_base_path in api_config.php. |
| Invalid bounds / coverage error | Use EPSG:4326 lon/lat bounds and a mode that covers the requested area. |
| Minimum area error | Select a larger area for os_tourism or os_vector. |