Proximity
Copy link

Measure how close everyday places are in walking and driving time, rather than distance. For every H3 cell, the endpoint returns a walk, transit and drive rating, the time to the nearest supermarket, school, station or brand, and how much is within 5, 10 and 15 minutes' walk.

This page answers questions such as:

  • How walkable is this location, and do you need a car there?
  • Which areas are within 5 minutes' walk of a supermarket?
  • How many cafés are within a 10-minute walk?

The walk and drive times are calculated by TravelTime. We precompute them from every H3 cell that people live in, up to 15 minutes. They are listed as traveltime in source_ids on /v1/catalog/{country}, with updated_at giving the date they were last loaded. In a country where no times have been built, every request returns no rows.

The Data API never calls the TravelTime API live. For longer journeys, send the H3 cells of a TravelTime catchment as cells (see Use with the TravelTime API).

Request headers
Copy link

Required authentication header. Use the same application id as for the TravelTime API.

string

Required authentication header.

Proximity ratings and travel times per H3 cell
Copy link

GET /v1/proximity/cells

Returns one row per H3 cell, or totals over what you send: one row per boundary with group_by=borough, or one row for everything with group_by=all.

Only resolution 9 is supported, but a group_by=all total also accepts coarser ids. Rows are in the order sent when you use cells, and in cell id order otherwise.

For long lists of cells, POST /v1/proximity/cells takes the same fields as a JSON body (see Long requests).

Parameters
Copy link

ParameterTypeDefaultWhat it doesExample
withintravel.target:seconds, comma-separated—A filter that keeps only the H3 cells that meet every condition, up to 10 conditions. travel is walk or drive. target is a category or group id, train_station, metro_station (underground, metro and tram), bus_stop, transit_stop (any of those), beach or brand:<slug>. All of them are listed in the proximity entry's targets on /v1/catalog/{country}. seconds is from 1 to 900. With country=gb, it searches the whole country.within=walk.supermarket:600,drive.brand:lidl:900
beyondas within—The opposite filter to within. Keeps the H3 cells that people live in where the nearest target is further away than the given time or out of reach, as well as those with no times.beyond=walk.transit_stop:900
covered_byas within—Requires group_by. Adds covered_population and covered_share to each totals row, which give the people within that time, without dropping any H3 cells.covered_by=walk.train_station:900
includebands, open_spaces—bands adds what is within 5, 10 and 15 minutes' walk. open_spaces adds the biggest public spaces within 15 minutes' walk. Only for per-cell rows, with up to 100 rows a page.include=bands,open_spaces

The endpoint also takes the following common parameters:

Each row contains cell, ratings (walk, transit and drive, each 0–100), and walk_s and drive_s. These give the time in seconds to the nearest of the 8 essentials (supermarket, school, doctor, pharmacy, post_office, park, cafe, restaurant) and to every within and beyond target.

A time over 900 s is null and is listed in missing with the reason over_900_s. Where nobody lives, ratings, walk_s and drive_s are null with the reason no_residents. Where people live but the build has no times for them, the reason is no_times.

With include=bands, each row also has bands.walk.300, .600 and .900. Each band contains category_counts (supermarket, cafe, pharmacy, doctor, school, gym, pub), open_space_m2 (public open space in reach, m²), largest_area_m2 (the whole size of the biggest public space in reach), over_1ha_count, over_5ha_count and over_20ha_count (counted by whole size), and green_m2 and green_share (green cover in reach).

With include=open_spaces, each row also has open_spaces. Each open space has id, name, class, access, area_m2 (its whole size, m²), reachable_m2 (the part inside the walk, m²) and walk_s_from_cell.

If the build does not have a band field other than category_counts, or does not have open_spaces, that field is null with the reason not_in_build. Where the source of a band field does not reach, the reason is outside_source_coverage. H3 cells with no walk times get neither bands nor open_spaces.

Totals rows contain boundary (with a boundary type), cell_count, population, the ratings and times, and covered_population and covered_share with covered_by. The rollup is sum for counts and people, population_weighted_mean for ratings and times (over the H3 cells that have them), and ratio_of_sums for covered_share.

Errors

CodeHTTPWhen
invalid_within · invalid_beyond · invalid_covered_by400The value is not in the form travel.target:seconds, the seconds are outside 1–900 (allowed_max 900), there are more than 10 conditions, or the country has no times for a target (the message lists them).
covered_by_needs_group_by400covered_by is sent with group_by=cell.
too_many_cells400country is sent without within or beyond; a search, including a country search, matches more than 100,000 H3 cells (use group_by); more than 100,000 cells are sent, unless group_by=all; or, with group_by=all, the cells sent cover more than 200,000 res-9 cells.
invalid_include400The value is not bands or open_spaces, or include is used with a group_by other than cell.
invalid_format400The value is not json or geojson, or geojson is requested with a group_by other than cell.
invalid_limit400limit is below 1 or over 10,000, or over 100 with include.

The endpoint can also return any of the Location, Per-cell endpoints and Paging error codes.

1. Send one cell, get one row
Copy link

Put the id of one H3 cell in cells. You get back one row for that cell. ratings scores the cell from 0 to 100 on foot, by public transport and by car. walk_s and drive_s are the walking and driving times, in seconds, to the nearest supermarket, school and other essentials.

You send

curl -H "X-Application-Id: YOUR_APP_ID" -H "X-Api-Key: YOUR_APP_KEY" \
  "https://data.traveltimeapp.com/v1/proximity/cells?cells=89195da4d03ffff"

You get

{
  "resolution": 9,
  "results": [
    {
      "cell": "89195da4d03ffff",
      "ratings": {
        "walk": 99,
        "transit": 100,
        "drive": 90
      },
      "walk_s": {
        "supermarket": 237,
        "school": 237,
        "doctor": 237,
        "pharmacy": 237,
        "post_office": 237,
        "park": 375,
        "cafe": 237,
        "restaurant": 237
      },
      "drive_s": {
        "supermarket": 424,
        "school": 424,
        "doctor": 424,
        "pharmacy": 424,
        "post_office": 424,
        "park": 424,
        "cafe": 424,
        "restaurant": 424
      }
    }
  ],
  "next_cursor": null
}

2. Send several cells, get one row for each
Copy link

Separate the cell ids with commas. You get one row for each cell, in the order you sent them. These seven cells lie between Euston and St Pancras. The map shades each cell by its walk rating, from 94 to 99. Select a cell to see its row.

Request

curl -H "X-Application-Id: YOUR_APP_ID" -H "X-Api-Key: YOUR_APP_KEY" \
  "https://data.traveltimeapp.com/v1/proximity/cells?cells=89195da4d03ffff,89195da4d07ffff,89195da4d0bffff,89195da4d0fffff,89195da4d13ffff,89195da4d17ffff,89195da4d1bffff"
200 · 7 H3 cells

Shade = ratings.walk94997 H3 cells; click a cell to open its row.

3. Add them up: one row for all the cells
Copy link

Add group_by=all to get one total row instead. The same seven cells are home to 6,869 people. Their ratings and times are averaged by population: a walk rating of 97, for example. rollup says how each field was added up.

For a long list of cells, send POST /v1/proximity/cells with the same fields in a JSON body. See Long requests.

You send

curl -H "X-Application-Id: YOUR_APP_ID" -H "X-Api-Key: YOUR_APP_KEY" \
  "https://data.traveltimeapp.com/v1/proximity/cells?cells=89195da4d03ffff,89195da4d07ffff,89195da4d0bffff,89195da4d0fffff,89195da4d13ffff,89195da4d17ffff,89195da4d1bffff&group_by=all"

You get

{
  "results": [
    {
      "cell_count": 7,
      "population": 6869,
      "ratings": {
        "walk": 97,
        "transit": 100,
        "drive": 90
      },
      "walk_s": {
        "supermarket": 303,
        "school": 241,
        "doctor": 214,
        "pharmacy": 336,
        "post_office": 297,
        "park": 280,
        "cafe": 213,
        "restaurant": 213
      },
      "drive_s": {
        "supermarket": 370,
        "school": 381,
        "doctor": 370,
        "pharmacy": 370,
        "post_office": 370,
        "park": 370,
        "cafe": 370,
        "restaurant": 370
      }
    }
  ],
  "next_cursor": null,
  "rollup": {
    "cell_count": "sum",
    "population": "sum",
    "ratings": "population_weighted_mean",
    "walk_s": "population_weighted_mean",
    "drive_s": "population_weighted_mean"
  }
}

4. No cell ids yet? Send an area
Copy link

Send bbox (south, west, north, east) for a box, or near and radius_m for a circle. You get one row for every cell in the area, and each row has its cell id. This box around King's Cross holds 39 cells.

Request

curl -H "X-Application-Id: YOUR_APP_ID" -H "X-Api-Key: YOUR_APP_KEY" \
  "https://data.traveltimeapp.com/v1/proximity/cells?bbox=51.522,-0.140,51.538,-0.110"
Examples

The walk rating is based on the walking times to the 8 essentials in walk_s. The ratings (walk / transit / drive) are 96 / 100 / 90 for King's Cross, 95 / 100 / 90 for Croydon centre, 77 / 32 / 67 for Bourton-on-the-Water and 52 / 21 / 100 for a Milton Keynes estate. Nobody lives on the Cotswolds farmland, so it has no rating.

Request

curl -H "X-Application-Id: YOUR_APP_ID" -H "X-Api-Key: YOUR_APP_KEY" \
  "https://data.traveltimeapp.com/v1/proximity/cells?cells=89195da4d8fffff,89194ac2677ffff,89195d48563ffff,89195d88a97ffff,89195d49b53ffff"
200 · 5 H3 cells

Shade = ratings.walk52965 H3 cells; click a cell to open its row.

Returns the 22 H3 cells around King's Cross that have a supermarket within a 5-minute walk.

An H3 cell must meet every condition: a supermarket within 10 minutes' walk, a train station within 5 minutes' walk and a Lidl within 15 minutes' drive. country=gb searches the whole country and finds 1,257 cells, where 572,651 people live (group_by=all gives that total).

With include=bands, each row also counts what is within 5, 10 and 15 minutes' walk. From one H3 cell at Euston, there are 5 supermarkets within 5 minutes' walk, 12 within 10 minutes and 59 within 15 minutes. For gyms the counts are 0, 12 and 46, and for cafés 10, 73 and 273.

To look for large open spaces rather than many small gardens, use the size counts. For example, "two parks of 5 ha within 15 minutes" is one check: an over_5ha_count of 2 or more. include=open_spaces lists the spaces by name. From Euston, you can reach The Regent's Park (117.6 ha) in 15 minutes. From the Milton Keynes estate, you can reach two spaces over 20 ha, including Teardrop Lakes (25.6 ha) in 8 minutes, and from Woodgreen, Godshill Inclosure (140.6 ha) in 7 minutes.

For house hunting, send the H3 cells of a TravelTime catchment and keep those with a supermarket within a 5-minute walk. Of the 8,526 cells within 45 minutes of King's Cross by public transport, 1,912 pass. This example sends seven of them, and 4 pass.

Find out how many of the people in each borough of your H3 cells live within 15 minutes' walk of a train station. covered_by reports this on the totals rows without dropping any cells, whereas within would act as a filter. Over the whole 45-minute catchment, 4,413,538 of 6,075,764 people (73%) live within that walk. This example sends seven of its cells, in Barnet and Brent.

Returns the H3 cells within a 15-minute walk of any transit stop, whether rail, Underground, tram or bus. beyond=walk.transit_stop:900 returns the cells that are further away.

Try these requests in the playground →