Green space

The green space dataset contains parks, forests, gardens and other open land as polygons. You can ask which named green spaces are near a point, or how much of an area is green. This page explains where the polygons come from, how they map to H3 cells and how to query them.

Source

The green space dataset comes from the land data in Overture Maps. Overture combines several sources, mostly OpenStreetMap, and tidies the classes. We take the polygons again with every data update.

Each polygon has four fields.

A geometry. The shape on the ground, in WGS 84 coordinates. Hyde Park in London is its mapped boundary. A forest is its mapped extent.
A class. What kind of place it is. See Classes.
A name. Where one exists. A grass verge or an unnamed pond has no name.
An id. Overture's UUID for the polygon. Use it to join to other Overture data.

Classes

Polygons come in two groups, each with sub-classes.

Land. Forest, wood, beach, sand, dune, wetland, island, heath, grassland and meadow. These are natural areas.
Land use. Park, village green, dog park, nature reserve, national park and the other classes people use.

The API groups the sub-classes into two type values. green-space holds every class except beaches. beaches holds beach, sand and dune. Every land cover endpoint returns both types unless you set type.

How polygons map to H3 cells

We split every polygon into the H3 cells it covers. We do this at resolution 9, with edges of about 175 m, and at resolution 10, with edges of about 65 m. For each cell we store which polygons touch it, with their class, their name and their area. A query reads those cells. You never see the polygons as separate rows.

To get the green space inside a travel time, send the reachable cells to GET /v1/h3/land-cover.

The TravelTime API returns the H3 cells you can reach. See Use with the TravelTime API.
Send those cells to GET /v1/h3/land-cover, or to POST /v1/h3/land-cover when the list is long.
The response has one row per cell and type, green space or beaches. Each row lists its polygons and its area, and the response carries one total, reachable_area_m2. See How area is calculated.

bash

curl -H "Authorization: Bearer $POI_API_KEY" \
  "$POI_BASE/v1/h3/land-cover?country=GB&cells=89195da494bffff,89195da494fffff"

This returns two cells inside Hyde Park. Each cell lists Hyde Park with its overture_id, its sub_class of park and its area_m2.

Query green space

There are four endpoints. All of them read the same green space data.

Endpoint	What to use it for
`GET /v1/h3/land-cover`	The green space in each cell. Use it for a surface, a heatmap or a reachable area.
`POST /v1/h3/land-cover`	The same query with the cell list in a JSON body, for long lists.
`GET /v1/polygons`	One row per polygon in an area, largest first. Use it for a list of named places.
`GET /v1/polygons/{polygon_id}/cells`	Every H3 cell one polygon covers.

GET /v1/h3/land-cover takes the standard geographic input: exactly one of cells, bbox, or center_lat with center_lng and radius_m. resolution is 9 or 10. The default is 9.

bash

curl -H "Authorization: Bearer $POI_API_KEY" \
  "$POI_BASE/v1/h3/land-cover?country=GB&bbox=51.50,-0.17,51.52,-0.15&resolution=9&limit=50"

type keeps one type: green-space or beaches. include and exclude filter by sub-class. include=park keeps parks and drops the gardens and recreation grounds in the same cells.

bash

curl -H "Authorization: Bearer $POI_API_KEY" \
  "$POI_BASE/v1/h3/land-cover?country=GB&bbox=51.50,-0.17,51.52,-0.15&resolution=9&limit=50&include=park"

GET /v1/polygons returns one row per polygon, largest first. Use it when you want a list of named places.

bash

curl -H "Authorization: Bearer $POI_API_KEY" \
  "$POI_BASE/v1/polygons?country=GB&bbox=51.50,-0.17,51.52,-0.15&limit=10"

It takes exactly one of bbox or cells. A request with both, or with neither, returns 400 with the code invalid_input. There is no country-wide list. limit defaults to 100 and the maximum is 1,000.

area_m2 is the area of the whole polygon, including any part outside your query. The same is true of polygons[].area_m2 on GET /v1/h3/land-cover. The clipped figure is reachable_area_m2, on each cell row and as a total for the whole response.

Full parameter and response shapes are in the API reference: land cover and polygons.

How area is calculated

GET /v1/h3/land-cover returns reachable_area_m2 on each cell row and on the response envelope. A row's figure is the polygon area inside that cell for that type. Each polygon's area is an approximation from its bounding box, spread evenly over the cells it covers. A polygon listed under two sub-classes counts under one. Each row is capped at the cell's own area, so overlapping, nested or duplicate polygons can never add up to more than the cell. A row's figure does not depend on which other types you request. The endpoint never sees your travel time. It only knows the cells you sent.

The envelope total is the sum of every row, so limit does not change it, and totals for separate sets of cells add up. Each cell keeps only its largest polygons. Polygons beyond that cut are missing from the total, which can bias it either way. Bounding boxes are larger than the polygons inside them, so a thin or irregular polygon still reads high in a cell it only partly covers.

A polygon at the edge of a reachable area counts in part. This is more accurate than counting a polygon as inside or outside.

To turn the total into a share, request type=green-space and divide its total by the area of the cells you sent.

text

open_space_pct = reachable_area_m2 / sum(reachable cell area)

A share of 73% means 73% of the reachable area, by area, is inside a green space polygon. Parks, forests, gardens and recreation grounds all count.

Places with the same name

Two polygons with the same name stay separate. Hyde Park in central London and Hyde Park in Manchester are two polygons in two disjoint sets of cells. We never merge polygons by name. Merging by name would add two parks in different cities into one figure.

Two polygons with the same name can overlap one cell. This is rare, and happens near the edge of a city region. Both count. The cell's polygons list then names Hyde Park twice, with different ids and different areas.

We recommend you do not deduplicate polygons by name in your own code. For analytics across cities, this keeps a figure such as park area per square kilometre correct.

Edge cases

Very large polygons are left out. Country boundaries, marine areas and any polygon larger than 5,000 km² are dropped before we map them to cells. The largest park or forest you see is well below this cap.
Very small polygons appear at resolution 9 only. Polygons under 70 m across, such as small ponds and garden plots, are mapped at resolution 9 and not at resolution 10. A resolution 10 cell is smaller than the polygon, so the area would be noisy. Resolution 9 queries see them. Resolution 10 queries do not.
Polygons can change between updates. Overture refines and simplifies boundaries between releases. last_refreshed in GET /v1/stats?country=GB tells you the date of the data you are reading. If you cache polygon results, key them on it. See Data updates.
Water is not included. Lakes, rivers, ponds, reservoirs and canals are not in the dataset. Overture's water data was too patchy to include. The Thames and several central London lakes are missing from it in places. Wetlands are included through the wetland class, so a marsh or fen appears. A lake or river does not.