Regions API #

The Regions API provides access to Project Sidewalk's region (neighborhood) data, including each region's boundary geometry and summary statistics such as the number of accessibility labels, streets, contributing users, and completed audits. Project Sidewalk divides each city into regions to organize exploration and track progress.

Regions API Preview #

Below is a live preview of region data from Hackensack, NJ retrieved directly from the API. Each neighborhood is color-coded by a statistic of your choice—use the Color by dropdown to switch between label count, completed audit count, and contributing user count. Hover and click on a region to view more information.

Endpoint#

Retrieves a list of regions, optionally filtered by the Query Parameters below.

GET /v3/api/regions

Quick Download #

Download region data directly in your preferred format:

Note: This downloads all region data. For filtered data, use the API Query Parameters described below.

Query Parameters#

Filter the regions returned by this endpoint using the following query parameters. All parameters are optional. Combine multiple filter parameters to narrow down results (filters are applied using AND logic).

Note: When multiple location filters are provided (bbox, regionId, and regionName), bbox takes precedence over region filters, and regionId takes precedence over regionName.

Responses#

Success Response (200 OK)#

On success, the API returns an HTTP 200 OK status code and the requested data in the specified filetype format.

GeoJSON Format (Default) #

Returns a GeoJSON FeatureCollection where each feature represents a single region. Coordinate Reference System (CRS) is WGS84 (EPSG:4326).

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "MultiPolygon",
                "coordinates": [
                    [
                        [
                            [-74.0243606567383, 40.8839912414551],
                            [-74.0244835449219, 40.8838416503906],
                            [-74.0245123456789, 40.8836789012345],
                            [-74.0243606567383, 40.8839912414551]
                        ]
                    ]
                ]
            },
            "properties": {
                "region_id": 8,
                "name": "Teaneck Community Charter School",
                "label_count": 423,
                "street_count": 36,
                "user_count": 12,
                "audit_count": 58,
                "first_label_date": "2023-06-20T14:32:45Z",
                "last_label_date": "2023-08-15T10:22:18Z"
            }
        },
        ...
    ]
}

GeoJSON Field Descriptions #

Each feature in the GeoJSON response represents a single region with MultiPolygon geometry and detailed properties:

CSV Format #

If filetype=csv is specified, the response body will be CSV data. The first row contains the headers, corresponding to the fields in the GeoJSON properties object, plus a geometry representation. CRS is WGS84 (EPSG:4326).

region_id,name,label_count,street_count,user_count,audit_count,first_label_date,last_label_date,center_point
8,Teaneck Community Charter School,423,36,12,58,2023-06-20T14:32:45Z,2023-08-15T10:22:18Z,"-74.0244835449219,40.8838416503906"
...

Note: The complete MultiPolygon geometry is simplified to a single center point in the CSV format due to the tabular nature of CSV. For full geometry data, use the GeoJSON format.

Shapefile Format #

If filetype=shapefile is specified, the response body will be a ZIP archive containing the Shapefile components (.shp, .shx, .dbf, .prj). The attribute table (.dbf) contains fields corresponding to the GeoJSON properties object (field names may be truncated due to Shapefile limitations). The included .prj file defines the Coordinate Reference System (CRS), typically WGS84 (EPSG:4326).

GeoPackage Format #

If filetype=geopackage is specified, the response body will be a GeoPackage (.gpkg) file containing the region data with full geometry and attributes. GeoPackage is a modern, open standard geospatial format that supports complex geometries and is widely supported by GIS software.

Error Responses#

If an error occurs, the API will return an appropriate HTTP status code and a JSON response body containing details about the error.

• 400 Bad Request: Invalid parameter values (e.g., malformed bounding box, invalid region ID).
• 404 Not Found: The requested resource does not exist (e.g., incorrect base URL path).
• 500 Internal Server Error: An unexpected error occurred on the server.

Error Response Body #

Error responses include a JSON body with the following structure:

{
    "status": 400, // HTTP Status Code repeated
    "code": "INVALID_PARAMETER", // Machine-readable error code
    "message": "Invalid value for bbox parameter. Expected format: minLng,minLat,maxLng,maxLat.", // Human-readable description
    "parameter": "bbox" // Optional: The specific parameter causing the error
}

Best Practices#

When working with the Regions API, consider these recommendations:

• Choose the right format: Use geojson for web mapping applications, csv for basic data analysis, shapefile for traditional GIS software, and geopackage for modern GIS workflows.
• Combine with other APIs: Use the Regions API alongside the Streets API, Label Clusters API, and Raw Labels API to drill down from regions to individual streets and labels.

Contribute#

Project Sidewalk is an open-source project created by the Makeability Lab and hosted on GitHub. We welcome your contributions! If you found a bug or have a feature request, please open an issue on GitHub.

You can also email us at sidewalk@cs.uw.edu

Project Sidewalk in Your City!#

If you are interested in bringing Project Sidewalk to your city, please read our Wiki page.