Cities API #

The Cities API lists all cities where Project Sidewalk is deployed and includes the city's name, ID, and URL as well as geographic information such as the city center point <lat, lng> and bounding box.

Cities API Preview #

Below is a live preview of the Cities API showing all deployment cities on a map. Hover over a city marker to see its name, and click to visit its Project Sidewalk site.

Loading cities data...

Endpoint #

Retrieve information about all Project Sidewalk deployment cities.

GET /v3/api/cities

Examples#

/v3/api/cities?filetype=json Get all cities in JSON (default)

/v3/api/cities?filetype=csv Get all cities in csv

/v3/api/cities?filetype=geojson Get all cities in geojson

Quick Download #

Download cities data directly in your preferred format:

Query Parameters#

This endpoint accepts the following optional query parameters to filter the cities returned.

Parameter	Type	Description
`filetype`	`string`	Specify the output format. Options: `json` (default), `csv`, `geojson`.

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.

JSON Format (Default) #

Returns a JSON object with a status field and a cities array containing information about each city.

{
    "status": "OK",
    "cities": [
        {
            "cityId": "teaneck-nj",
            "countryId": "usa",
            "cityNameShort": "Teaneck",
            "cityNameFormatted": "Teaneck, NJ",
            "url": "https://sidewalk-teaneck.cs.washington.edu",
            "visibility": "public",
            "centerLat": 40.888,
            "centerLng": -74.015,
            "zoom": 12.75,
            "bounds": {
                "north": 41.4,
                "south": 40.4,
                "east": -73.5,
                "west": -74.5
            }
        },
        {
            "cityId": "pittsburgh-pa",
            "countryId": "usa",
            "cityNameShort": "Pittsburgh",
            "cityNameFormatted": "Pittsburgh, PA",
            "url": "https://sidewalk-pittsburgh-test.cs.washington.edu",
            "visibility": "public",
            "centerLat": 40.435,
            "centerLng": -79.96,
            "zoom": 11.75,
            "bounds": {
                "north": 41,
                "south": 40,
                "east": -79,
                "west": -81
            }
        },
        // ... more cities
    ]
}

JSON Field Descriptions #

Each city object contains the following fields:

Field	Type	Description
`cityId`	`string`	Unique identifier for the city.
`countryId`	`string`	Identifier for the country where the city is located.
`cityNameShort`	`string`	Short name of the city.
`cityNameFormatted`	`string`	Full formatted name of the city, including state/province or country information.
`url`	`string`	URL for the city's Project Sidewalk instance.
`visibility`	`string`	Visibility status of the city: `public` or `private`.
`centerLat`	`number \| null`	Latitude of the city's center point. Present only if geographic information is available.
`centerLng`	`number \| null`	Longitude of the city's center point. Present only if geographic information is available.
`zoom`	`number \| null`	Recommended zoom level for map display. Present only if geographic information is available.
`bounds`	`object \| null`	Geographic boundaries of the city. Present only if geographic information is available.
`bounds.north`	`number`	Northern boundary (maximum latitude).
`bounds.south`	`number`	Southern boundary (minimum latitude).
`bounds.east`	`number`	Eastern boundary (maximum longitude).
`bounds.west`	`number`	Western boundary (minimum longitude).

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 JSON response.

cityId,countryId,cityNameShort,cityNameFormatted,url,visibility,centerLat,centerLng,zoom,bounds.north,bounds.south,bounds.east,bounds.west
teaneck-nj,usa,Teaneck,"Teaneck, NJ",https://sidewalk-teaneck.cs.washington.edu,public,40.888,-74.015,12.75,41.4,40.4,-73.5,-74.5
pittsburgh-pa,usa,Pittsburgh,"Pittsburgh, PA",https://sidewalk-pittsburgh-test.cs.washington.edu,public,40.435,-79.96,11.75,41,40,-79,-81
...

GeoJSON Format #

If filetype=geojson is specified, the response body will be a GeoJSON FeatureCollection. Cities with geographic information are represented as Point features. Cities without geographic coordinates are omitted from the GeoJSON output.

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [-74.015, 40.888] // [longitude, latitude]
            },
            "properties": {
                "cityId": "teaneck-nj",
                "countryId": "usa",
                "cityNameShort": "Teaneck",
                "cityNameFormatted": "Teaneck, NJ",
                "url": "https://sidewalk-teaneck.cs.washington.edu",
                "visibility": "public",
                "zoom": 12.75,
                "bounds": {
                    "north": 41.4,
                    "south": 40.4,
                    "east": -73.5,
                    "west": -74.5
                }
            }
        },
        // ... more cities with geographic information
    ]
}

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.
404 Not Found: The requested resource does not exist.
500 Internal Server Error: An unexpected error occurred on the server.
503 Service Unavailable: The server is temporarily unable to handle the request.

Error Response Body #

Error responses include a JSON body with the following structure:

{
    "status": 400, // HTTP Status Code
    "code": "INVALID_PARAMETER", // Machine-readable error code
    "message": "Invalid value for visibility parameter. Expected 'public' or 'private'.", // Human-readable description
    "parameter": "visibility" // Optional: The specific parameter causing the error
}

Terms of Use #

If you use Project Sidewalk data in your research, please cite the following paper (awarded 🏆 Best Paper at CHI 2019):

Manaswi Saha, Michael Saugstad, Hanuma Teja Maddali, Aileen Zeng, Ryan Holland, Steven Bower, Aditya Dash, Sage Chen, Anthony Li, Kotaro Hara, and Jon Froehlich. 2019. Project Sidewalk: A Web-based Crowdsourcing Tool for Collecting Sidewalk Accessibility Data At Scale. In Proceedings of the 2019 CHI Conference on Human Factors in Computing Systems (CHI '19). Association for Computing Machinery, New York, NY, USA, Paper 62, 1–14. https://doi.org/10.1145/3290605.3300292

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.