POST /geometry/image

Renders a site boundary over background mapping and returns the image as a PNG.

Base URL: https://geoapi.geocerta.io

Sandbox URL: https://geoapi-staging.geocerta.io

Authentication required. Include your API key in the api-key header. See Authentication.

Endpoint

POST /geometry/image

Content-Type: application/json

Request Body

Supply the site geometry as either geometry (GeoJSON, WGS84) or wkt (British National Grid) — exactly one of the two. Every other field is optional.

Field	Type	Required	Description
`geometry`	GeoJSON geometry	One of the two	Geometry in WGS84 (EPSG:4326). `type` must be `Point`, `Polygon`, or `MultiPolygon`.
`wkt`	string	One of the two	Geometry as a WKT string in British National Grid (EPSG:27700) — the same format `POST /geometry/data` returns.
`zoom`	integer	No	Zoom level, `7`–`20`. Omit to fit the geometry automatically.
`width`	integer	No	Image width in pixels, `1`–`2048`. Default `800`.
`height`	integer	No	Image height in pixels, `1`–`2048`. Default `600`.
`boundary_color`	string	No	Boundary colour as a 6-digit hex string, e.g. `#0000ff`. Default `#ff0000`.
`boundary_width`	number	No	Boundary line width in pixels. Default `2`.
`fill_color`	string	No	Fill colour as a 6-digit hex string. Omit to leave the boundary unfilled.
`fill_opacity`	number	No	Fill opacity, `0`–`1`. Only applies when `fill_color` is set. Default `0`.
`scale_bar`	boolean	No	Draw a metric scale bar in the bottom-left corner. Default `true`.
`licence`	boolean	No	Draw the mapping data copyright attribution in the bottom-right corner. Default `true`.

Unknown fields are rejected with a 400.

Choosing a zoom

Omit zoom and the image is framed to fit the geometry — the closest zoom at which the whole site fits inside the image with a small margin. This is the right choice for most uses.

Set zoom explicitly when you need a consistent scale across several images, for example when placing them side by side in a report. The image is then centred on the site at exactly that zoom, and a site larger than the frame is cropped.

A Point with no zoom is rendered at zoom 16.

A zoom outside 7–20 is rejected with a 400 rather than adjusted, so you never receive an image at a scale you did not ask for.

Scale bar and attribution

Every image carries a scale bar in the bottom-left corner and the mapping data copyright attribution in the bottom-right corner. The scale bar shows a round distance, for example 50 m or 2 km, sized to the zoom of the image.

Both are on by default. Set scale_bar or licence to false to leave one out. The attribution is a condition of the mapping data licence; if you switch it off, displaying the attribution alongside the image becomes your responsibility.

Small images leave them out automatically so they never overlap the site. The attribution is omitted when the image is narrower than 520 pixels, the scale bar when it is narrower than 160 pixels, and both when it is shorter than 40 pixels.

Response

200 OK — the raw PNG image.

Content-Type: image/png

The response body is the image itself, not a JSON object, so write it straight to a file or stream it to your client.

A site outside the area covered by the background mapping returns a 200 with the boundary drawn over a blank background, not an error.

Errors

Errors are returned as JSON with an error field describing what went wrong:

Status	Cause	Example `error`
`400`	Neither `geometry` nor `wkt` given, or both	`" - exactly one of geometry or wkt is required"`
`400`	A value outside its allowed range	`"width - Too big: expected number to be <=2048"`
`400`	A colour that is not a 6-digit hex string	`"boundary_color - must be a 6-digit hex colour, e.g. #ff0000"`
`400`	A `scale_bar` or `licence` value that is not a boolean	`"licence - Invalid input: expected boolean, received string"`
`400`	An unsupported geometry type	`"geometry.type - Invalid option: expected one of "Point"\|"Polygon"\|"MultiPolygon""`
`400`	A `wkt` that cannot be parsed	`"wkt must be a POINT, POLYGON or MULTIPOLYGON"`
`400`	An unknown field	`" - Unrecognized key: "style""`
`401`	Missing or invalid API key	`"Invalid API key"`
`403`	The API key is not permitted to use this endpoint	`"Account owner access required"`
`502`	The background mapping could not be retrieved	`"Could not fetch the background mapping"`

Example

Render a site from a BNG WKT, letting the endpoint choose the zoom, and save it to a file:

curl -X POST https://geoapi.geocerta.io/geometry/image \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -o site.png \
  -d '{
    "wkt": "POLYGON((530000 180000, 530100 180000, 530100 180100, 530000 180100, 530000 180000))"
  }'

Render from GeoJSON at a fixed zoom, as a wider image with a blue boundary and a translucent fill:

curl -X POST https://geoapi.geocerta.io/geometry/image \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -o site.png \
  -d '{
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [-0.1280, 51.5030],
          [-0.1270, 51.5030],
          [-0.1270, 51.5036],
          [-0.1280, 51.5036],
          [-0.1280, 51.5030]
        ]
      ]
    },
    "zoom": 18,
    "width": 1200,
    "height": 600,
    "boundary_color": "#0000ff",
    "boundary_width": 3,
    "fill_color": "#0000ff",
    "fill_opacity": 0.15
  }'

Using it with an order

POST /geometry/data returns a wkt field for a validated site. Pass that same string straight to this endpoint to produce the siteplan.