Supply Shed Isochrones

The /supply_shed/ API endpoint returns supply shed polygons as GeoJSON. These can be either: - Travel-time isochrones (motorized travel-time polygons) when you provide travel_times, or - Distance buffers (naive radius circles) when you provide radii.

The idea is to merge multiple base rasters (water, elevation, landcover, road, border) into a 'cost' layer where each pixel represents travel time. This travel time is cumulated so that each pixel becomes the travel time relative to the defined starting pixel. This cumulative cost raster is thresholded by user-provided travel times to be vectorized into isochrones.

The below visual shows the high-level flow used to compute the travel-time isochrones.

Key Datasets

1. Landcover: ESA WorldCover v100 via Planetary Computer

The landcover raster classifies each (10x10)m area as a terrain type (tree cover, shrubland, grassland, cropland, built-up, sparse vegetation, snow and ice, permanent water bodies, herbaceous wetland, mangroves, moss and lichen)

1. Elevation/Slope: Copernicus DEM GLO-30 via Planetary Computer

The elevation raster stores elevation levels for each (30x30)m area. The slope raster utilizes elevation levels to compute the incline for each pixel as a value between [0, 90]

1. Water: JRC Global Surface Water via Planetary Computer

The water raster tracks water occurence across the 12 months

1. Road: Overture Maps Roads

The road dataset contains road vectors (LineString) and their properties, including surface material, road type, and length

1. Border: geoBoundaries (ADM0), v6.0.0 via EarthEngine and the GeoBoundaries API

The border dataset contains national borders (Polygon/MultiPolygon) and basic information on each country, such as the country code.

Key Considerations

1. Runtime: The runtime is quite long due to the need to load multiple base rasters and download the computed friction raster to perform cumulative cost on. Projected runtime is about 0.5-2 minutes for radii between 10-30km and scales exponentially as radii increases. To reduce runtime:
2. Choose a smaller resolution as higher resolutions will reduce the computation time exponentially. The recommended resolution is 100. To illustrate, consider a (100x100)km bounding box. For 50m resolution, this becomes a (2000x2000) raster whereas for 100m resolution it is (1000x1000). The total pixels is 4m versus 1m which is a $\frac{100m}{50m}^2$ decrease. However, scaling resolution may unpredictably, albeit slightly, change the formed isochrones due to working with reduced precision

Authentication

This endpoint requires authentication via a Bearer token in the Authorization header.

Parameters

There are 2 ways of calling the endpoint:

1. Via a geometry string (WKT format) representing a Polygon or Point - if a Polygon is provided, its bounds are used; otherwise the centroid is used as the starting point
2. Via latitude, longitude, and optionally radius (in meters)

Required Parameters

Parameter	Type	Description
Authorization	Header	Bearer token for authentication

Optional Parameters

Parameter	Type	Default	Description
geometry	string	None	WKT geometry string (Polygon or Point). If Polygon, uses bounds; otherwise uses centroid.
longitude	float	None	Longitude of the starting point (EPSG:4326)
latitude	float	None	Latitude of the starting point (EPSG:4326)
radius	float/int	0	Maximum search radius in meters. If 0, auto-calculated as max(travel_times) * 1200
radii	list[int]	[]	List of radii (m) to produce distance-based buffer supply sheds for. If provided and non-empty, these take precedence over travel_times (i.e. returns buffers instead of travel-time isochrones).
travel_times	list[int]	[120]	List of travel times in minutes to produce isochrones for

Note: Either geometry OR (latitude AND longitude) must be provided.

Distance vs travel-time: - travel_times produces motorized travel-time isochrones. - radii produces naive distance buffers (circles) around the start point (and is only supported for point inputs).

Units: - Travel time: minutes - Radius: meters - Resolution: meters - Latitude/longitude/geometry: EPSG:4326 (WGS84)

Response

The endpoint returns a GeoJSON FeatureCollection in NDJSON format (application/x-ndjson) with each isochrone as either a Polygon or MultiPolygon. Each feature includes:

• geometry: The isochrone polygon geometry
• properties: Metadata about the isochrone (typically including travel time information)

Response Headers: - Content-Type: application/x-ndjson - Content-Disposition: filename="isochrones.json"

Usage and Billing

The endpoint tracks usage based on the total area of generated isochrones: - Equivalent calls: Calculated as total_area_ha / 300,000 (where 300,000 hectares = 1 supply shed equivalent) - Plan limits: The endpoint checks your plan limits before processing and will return an error if limits are exceeded - Supply shed count: Each travel time in the travel_times list counts as one supply shed toward your plan limits

Example Usage

import requests

headers = {
    "Authorization": "Bearer <your_token>"
}

# Example 1: Using latitude/longitude
response = requests.get(
    "https://epoch-sco2-api.com/supply_shed/",
    headers=headers,
    params={
        "latitude": -6.2088,
        "longitude": 106.8456,
        "travel_times": [60, 120, 180],
        "resolution": 100
    }
)

# Example 2: Using geometry (WKT format)
response = requests.get(
    "https://epoch-sco2-api.com/supply_shed/",
    headers=headers,
    params={
        "geometry": "POINT(106.8456 -6.2088)",
        "travel_times": [120],
        "radius": 50000  # 50km radius
    }
)