Project Sidewalk is deployed in multiple cities across several countries. The Cities API lists all Project Sidewalk
deployment sites, including the city's name, ID, and URL as well as geographic information such as the
city center point lat, lng
and bounding box.
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.
Retrieve information about all Project Sidewalk deployment cities.
GET /v3/api/cities
/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
Download cities data directly in your preferred format:
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 . |
On success, the API returns an HTTP 200 OK
status code and the requested data in the specified
filetype
format.
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
]
}
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). |
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
...
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
]
}
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 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
}
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
If you are interested in bringing Project Sidewalk to your city, please read our Wiki page.