Cell features

Each H3 cell at resolution 9 has one feature document. It describes what is inside the cell: how many places of each category, the essential places and brands, the public transport stations and lines, the park area, the six environment measures and the census facts. Personal scoring reads these documents. This page explains what a document holds and how to query it.

What a document holds

Every document carries the cell's h3, country_code, location (the cell centre) and breadcrumb_ids, every administrative area the cell sits in. Nine blocks follow.

• counts is the number of distinct places in the cell per category id and group id, and transport, the number of stations. authority_aware counts a place when it is verified, an authoritative source files it under the category or at least two sources list it. raw counts every place. A zero count is left out.

• places lists up to five places inside the cell for each essential category, each of the country's brand:<slug> keys and beach, as {poi_id, source_count}.

• transit describes the stations inside the cell: station_count, line_ids, modes and max_tph_am_peak, the busiest line's services per hour in the morning peak.

• green carries area_m2, the area inside the cell of every land-cover green-space class, as in Green space.

• environment carries the noise, air, flood, deprivation, broadband and crime layers described in Environment. A layer with no source for the cell is null.

• census carries the cell's population and census rates, as in Population and areas.

• walk is a 15-minute walk from the cell centre, measured by TravelTime on a weekday morning. cells gives the seconds to every res-9 cell it reaches. bands sums what those cells hold within 300, 600 and 900 seconds: counts, green (area_m2 and share, the green fraction of the band's cells), transit (distinct lines and max_tph) and diversity, the Shannon index of the category counts. nearest gives, for every essential category, beach and category or group id, the seconds to the quickest cell that holds one, or null when none is reached. A brand: key appears only when that brand is reached.

• drive is the same for a 15-minute drive, over res-8 cells and without cells.

• scores rates the cell 0–100 on one scale used in every country. walk and drive weigh how quickly the essentials are reached (supermarket, school, doctor, pharmacy, post office, park, café, restaurant) and how much is within 15 minutes. transit weighs every line that stops within a 15-minute walk by its services per hour, its mode (rail counts double) and the walk to it. needs_car is true when walk and transit are both below 50.

walk, drive and scores are set on inhabited cells only. Their times are cell means, so a place's time is the time to its cell, not to its door. A mode with no fetched times has a null score.

Brand keys use every outlet of the brand, and beach also counts beach polygons. Essential categories, beach places and every other key apply the authority-aware rule, so counts.raw can exceed what nearest sees.

A null block or value means no source reaches the cell. It never means zero.

Travel time, not distance

No document carries a distance. A place's position is the cell it sits in. To ask how far away something is, fetch the cells a person can reach, for example with a TravelTime H3 request, and read their documents. The nearest supermarket is the quickest cell whose places lists one, and the walking time to that cell is the answer.

Query features

GET /v1/h3/features returns one document per cell. Send exactly one of bbox, cells or division, as for population. Add fields to return only some blocks. A block you leave out is absent from the response.

curl -H "Authorization: Bearer $POI_API_KEY" \
  "$POI_BASE/v1/h3/features?country=GB&cells=89194ad325bffff&fields=counts,transit"

Cells are sorted by h3. A cell with no document is left out of the result. There is no 404. limit defaults to 100 and the maximum is 10,000.

Filter by travel time

reach keeps the lived-in cells within a walk or drive of the nearest place of each key. Each condition is <walk|drive>.<key>:<max seconds>, from 1 to 900 seconds. Send up to 10, comma-separated; a cell must meet them all. A key is an essential (swimming_pool), one of the country's searchable brands (brand:lidl, its most widespread), beach, or any category or group id. Any other key is a 400 that lists the supported keys.

With reach the area is optional, and leaving it out searches the whole country.

curl -H "Authorization: Bearer $POI_API_KEY" \
  "$POI_BASE/v1/h3/features?country=GB&reach=walk.swimming_pool:600,walk.train_station:300&fields=scores"

Each cell carries the seconds for the filtered keys, for example "reach": {"walk.swimming_pool": 540, "walk.train_station": 240}. total is the number of matching cells and population the people living in them, including cells past limit.

Full parameter and response shapes are in the API reference.