Cities
Cities (#2064): the /cities index and map, one city page, following a city with its weekly digest and instant alerts, the MapKit token and the map snapshots. A city has a public page at 1+ verified Fundly or 5+ donors. Donor counts, follower counts and where gifts go show only at 5+; donors are never listed by city.
List cities
Every city with a verified Fundly or a donor, not hidden by staff. Cities below the page threshold are included with has_page: false (show them as plain text). totals are platform-wide and ignore q and area. near_you is the nearest city with a page within 100 miles of near, else of the signed-in viewer's profile city, else of the edge's viewer location headers when present; null otherwise. Authentication is optional and only feeds near_you.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Query Parameters
Matches the city name or its metro's name.
active: featured first, then live Fundlies, donors, raised. az: by name.
"active""az""active""all""us""intl""all"A lat,lng point for near_you.
"38.58,-121.49"15002400Responses
One page of cities
City map dots
The cities map as an image
A redirect to a signed Apple Maps Web Snapshot with the same dots when a MapKit key is configured, else the static map: an SVG of Natural Earth outlines with the dots, in Web Mercator. Use it as an image source; it works for both answers.
Parameters
Query Parameters
"us""world""us"6420481152642048480"light""dark""light"Responses
The static map
The one-click opt-out page
The link in every city email. Reads only (mail scanners prefetch links): an HTML page with a button that posts back, or the state as JSON when the caller asks for application/json.
Parameters
Query Parameters
"uuid""digest""instant""digest"Responses
The page, or the state
One-click opt-out
The List-Unsubscribe-Post target (RFC 8058) and the page's button: turns off that city's weekly digest (kind=digest) or instant alerts (kind=instant) for the follow the token names, and keeps the follow. Idempotent. No session: the token is the authorization. A mail client gets JSON; a browser form (it asks for text/html) is redirected to Settings, /profile/settings?city_digest_off={slug} for a digest.
Parameters
Query Parameters
"uuid""digest""instant""digest"Responses
Turned off
Get a city page
One city page. 404 (CITY_NOT_FOUND) unless the city has a page: 1+ verified Fundly or 5+ donors, or forced on by staff, and never while hidden. A slug retired by a rename or a merge serves the surviving city: city.slug is canonical, and a page should redirect to it when it differs. Authentication is optional and only personalizes follow; render the page server-side without it.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
"sacramento-ca"Query Parameters
Fundly titles in this language where a translation exists.
"en""ru""uk""es"Responses
The city
A city's map as an image
The map around one city (about 60 miles each way) with its dots: a redirect to a signed Apple Maps Web Snapshot when a MapKit key is configured, else the static SVG. 404 unless the city has a page.
Parameters
Path Parameters
Query Parameters
642048640642048360"light""dark""light"Responses
The static map
My follow of a city
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Responses
The follow block
Follow a city, or change its notifications
Idempotent. Creates the follow with the defaults (weekly digest on, instant alerts off) or changes only the switches given. The bell on the city page sends both false to silence a city without unfollowing. 404 when the city has no page.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Request Body
Responses
The follow block after the change
Unfollow a city
Idempotent. Works even after the city lost its page.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Parameters
Path Parameters
Responses
The follow block after the change
Cities I follow
Settings > Notifications > Cities you follow, newest first, and the Settings > Privacy switch show_followed_cities_to_friends (change it with PATCH /users/{id}). Change a city's switches with PUT /cities/{slug}/follow.
Authorizations
In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.
Responses
The follows
MapKit JS token
The token MapKit JS initializes with. Minted (a 30-minute ES256 token for this site's origin) when the server holds a MapKit key, else the static token configured for the site (expires_at null when it has no expiry), else 503 with code MAPKIT_NOT_CONFIGURED, and the page keeps its static map. Never cached.
Responses
A token