Cities API
Every city where FundlyHub money moves has a record: the verified Fundlies started there, the donors who live there, and the communities and non-profits placed there. A city with at least one verified Fundly or one donor has a public page at fundlyhub.org/cities/<slug>, and a signed-in person can follow it for a weekly digest and instant alerts. This page covers the public reads, the maps, following, and the privacy rules every read applies.
| Reference section | Operations | About |
|---|---|---|
| Cities | 12 | The `/cities` index and map, one city's page, and following a city: a weekly digest and instant alerts by email, a one-click opt-out from either, and the list of cities you follow; plus the MapKit JS token and static map snapshots. A city gets a public page once it has one verified Fundly or one donor who lives there, unless staff override that; below it, the city still shows on the map. Donor counts are exact from the first donor (signed in, guest or anonymous), while the follower count and where a city's gifts go show only from 5 followers and 5 donors. Donors are never listed by city. Reading needs no account; following needs a signed-in session. |
What counts, and in which unit
A verified Fundly is one that passed FundlyHub's approval, is public and is not deleted; nothing else counts for a city. Money is integer cents and means what reached the creators: each paid (or later refunded) gift at its donation less the Stripe fee, never the tip. A city's raised_cents is therefore the sum of its Fundlies' campaign cards.
Where a city comes from
A Fundly is placed in the city its location names, else the city its location geocodes to; a gift is placed in the donor's city, worked out from the gift's billing address and, failing that, from the donor's profile city; a community is placed from its city_text. Each city has one city-level point (lat, lng), never anything finer, and a slug: city and state in the US (sacramento-ca), city and country elsewhere (kyiv-ukraine). Names come from the geocoder in English, and no city field is translated for the reader.
Which cities have a page
A city has a page, and has_page: true, when it has at least one verified Fundly or one donor. FundlyHub can force a page on or off, and a city it has hidden has no page and appears in no public list. A city without a page still shows on the map and in the index: print its label as plain text rather than a link, because GET /cities/{slug} answers 404 for it.
Privacy floors
| What | Rule |
|---|---|
donors | Exact from the first donor (signed in, guest or anonymous); null when there are none. |
follow.follower_count | Shown at 5 followers or more; null below. |
gift_destinations, backed | Shown at 5 donors or more; null below. |
| Donors themselves | Never listed by city, to anyone. |
follow.friends | At most 3 faces: the caller's mutual follows who follow the city, minus anyone who turned off "Show the cities I follow to friends" or whose profile is not public. friend_count counts every friend who follows. |
The city card
CityCard is the row every list returns (data, near_you, nearby):
| Field | Notes |
|---|---|
slug, name, region, country | country is ISO 3166-1 alpha-2; in the US region is the state code. |
label | What to print: "Sacramento, CA" in the US, "Kyiv, Ukraine" elsewhere. |
photo_url | The square city photo, or null. |
lat, lng | The city's point. Pass it as near to GET /fundraisers for the campaigns around it. |
fundlies_active, fundlies_funded | Verified Fundlies started here that are live now, and that reached their goal. |
donors | Distinct donors who live here, or null. |
raised_cents | What the verified Fundlies started here raised. |
has_page | Whether GET /cities/{slug} answers. |
metro | { slug, name } of the metro's anchor city; null for an anchor or a city in no metro. |
Public reads
| Endpoint | Auth | Returns |
|---|---|---|
GET /cities | Optional | The index: a page of cards, platform totals and "near you". |
GET /cities/{slug} | Optional | One city page. |
GET /cities/map | Public | { points }, one dot per city. |
GET /cities/map/snapshot · GET /cities/{slug}/snapshot | Public | The map as an image. |
GET /maps/token | Public | The MapKit JS token FundlyHub's own map starts with. |
Credentials are optional on the index and the page and never cause a 401. On the index they only feed near_you; on a city page they fill in the follow block and the caller's state on the community and non-profit cards.
The index
GET /api/v1/cities
Every city with a verified Fundly or a donor (or a page FundlyHub forced on), whether or not it has a page.
| Query | Notes |
|---|---|
q | Case-insensitive substring of the city's name or its metro's name. Trimmed and cut to 80 characters; % and _ are literal. |
sort | active (default): most live Fundlies first, then most donors, then most raised, then by name. az: by name. Anything else is a 400. |
area | all (default), us or intl. Anything else is a 400. |
near | <lat>,<lng>, for near_you only; it does not filter the list. |
limit | 1–500, default 24. A missing, zero, negative or non-numeric value is 24; a larger one is 500. |
offset | Default 0. |
curl "https://api.fundlyhub.org/api/v1/cities?sort=active&limit=1"{
"data": [
{
"slug": "sacramento-ca",
"name": "Sacramento",
"region": "CA",
"country": "US",
"label": "Sacramento, CA",
"photo_url": null,
"lat": 38.58,
"lng": -121.49,
"fundlies_active": 12,
"fundlies_funded": 4,
"donors": 57,
"raised_cents": 1843200,
"has_page": true,
"metro": null
}
],
"total": 214,
"totals": {
"cities": 214, "us_cities": 188, "countries": 7, "us_states": 31,
"fundlies": 402, "fundly_cities": 129, "raised_cents": 51234500, "donors": 3110
},
"near_you": null,
"map_version": "1792000000-412"
}totalcounts the cities that matchqandarea; page through them withoffset.totalsis platform-wide and ignoresqandarea:cities(every city the index lists),us_cities,countries,us_states,fundlies(verified Fundlies placed in a city),fundly_cities(cities with at least one),raised_cents, anddonors(people who live in a city, each counted once however many cities they gave from).near_youis the nearest city with a page within 100 miles of a point, ornull. The point isnearwhen you send one. Withoutnearit is the viewer location the CDN edge forwards, when it forwards one, and otherwise, for a signed-in caller, their profile's city (that city when it has a page, else the nearest city with a page within 100 miles of it). A malformednearis not an error: it is ignored and only the profile city is tried.map_versionchanges whenever any city changes. Add it to the snapshot URLs asv, so a cached image never outlives the cities it draws; the server does not read it.
The index, the totals and the map dots are cached for up to five minutes.
One city
GET /api/v1/cities/{slug}
404 with { "error": "City not found", "code": "CITY_NOT_FOUND" } unless the city has a page. A slug retired by a rename or a merge answers with the surviving city: city.slug is canonical, so redirect to it when it differs from the one you asked for. The response is not wrapped in data:
{
"city": { "slug": "sacramento-ca", "label": "Sacramento, CA", "region_name": "California", "country_name": "United States", "timezone": "America/Los_Angeles", "has_page": true, "metro": null },
"stats": {
"fundlies_active": 12, "fundlies_funded": 4, "fundlies_here": 19, "city_impact_cents": 2650400,
"raised_here_cents": 1843200, "donors": 57, "given_from_here_cents": 977300,
"communities": 2, "nonprofits": 1, "churches": 1, "ambassadors": 3
},
"needs_help": [], "fully_funded": [], "communities": [], "nonprofits": [], "ambassadors": [], "nearby": [],
"gift_destinations": [{ "slug": "kyiv-ukraine", "name": "Kyiv", "label": "Kyiv, Ukraine", "has_page": true, "share": 0.31 }],
"backed": { "fundlies": 37, "cities": 12, "items": [] },
"follow": { "following": false, "digest": true, "instant": false, "follower_count": 9, "friends": [], "friend_count": 0 },
"map_version": "1792000000-412"
}(city is shortened here: it carries every card field too.)
| Field | Holds |
|---|---|
city | The card plus timezone, region_name, country_name, the photo fields (photo_original_url, photo_crop, photo_credit, photo_page_focus) and metro with place_count (for a metro's anchor, the city itself). |
stats | fundlies_here is every verified Fundly started here; given_from_here_cents is what donors here gave, to any Fundly; city_impact_cents is City impact, the figure the leaderboard shows for the city (money into the funds of communities here, plus raised here, given from here and driven from here, each gift counted once). nonprofits counts the non-profit cards that are not churches, churches the ones that are. |
needs_help | Up to 12 live verified Fundlies started here, newest first, as campaign cards. When none is live, the city's verified Fundlies that are neither live nor fully funded take their place. |
fully_funded | Up to 12 verified Fundlies here that reached their goal, most recently funded first. |
communities | Every listed community placed here, as directory cards, featured first, then the most members. See Communities. |
nonprofits | Every verified non-profit placed here, as directory cards; a card with is_church: true is a church. |
ambassadors | Up to 12 public profiles here holding the ambassador role, by money driven: name, avatar_url, handle, driven_cents, fundlies_organized. |
nearby | Up to 8 other cities with a page: the same metro first, then the nearest within 150 miles. |
gift_destinations | The top cities by share (0–1) of the money donors here gave. null below 5 donors. |
backed | { fundlies, cities, items }: what donors here backed, with up to 6 campaign cards. null below 5 donors. |
follow | The follow block, for the caller. |
The campaign cards honour ?lang= (below). The communities and nonprofits cards carry the caller's own viewer state, so send credentials if you show a Join or Follow button.
Maps
GET /cities/map?scope=world|us (default world) answers { "points": [...] }: one dot per city in the index (us keeps the US ones), each { slug, name, label, lat, lng, fundlies, donors, kind, has_page }. kind is fundlies for a city where Fundlies started and donors_only for a city with donors only; donors follows the floor above.
The two snapshot endpoints draw the same dots as an image:
| Endpoint | Frame | Default size |
|---|---|---|
GET /cities/map/snapshot?scope=us|world | The lower 48 (us, the default) or the world | 1152 × 480 |
GET /cities/{slug}/snapshot | About 27 km across, centred on the city; 404 without a page | 640 × 360 |
w and h are clamped to 64–2048, and scheme is light (default) or dark. The answer is a 302 to a signed Apple Maps Web Snapshot when FundlyHub holds a MapKit key, otherwise a 200 SVG of the same dots. Use the URL as an image source and both answers render. The redirect may be cached for an hour and the SVG for ten minutes.
GET /maps/token answers { "token": "…", "expires_at": "…" | null } with Cache-Control: no-store, or 503 with code: "MAPKIT_NOT_CONFIGURED". It exists for FundlyHub's own pages; it is not a way to get a MapKit token for another site.
Following a city
| Endpoint | Auth | Purpose |
|---|---|---|
GET /cities/{slug}/follow | Signed in | The caller's follow block. |
PUT /cities/{slug}/follow | Signed in | { "digest"?: boolean, "instant"?: boolean }: follow, or change the switches. |
DELETE /cities/{slug}/follow | Signed in | Unfollow. |
GET /me/city-follows | Signed in | Every city the caller follows, newest first. |
Following needs an account; there is no anonymous mailing list.
PUTis idempotent. A new follow starts with the weekly digest on and instant alerts off; on an existing follow only the switches you send change, so sending bothfalsesilences a city without unfollowing it. A switch that is not a boolean is a400, and a city without a page is a404.DELETEis idempotent, and it (likeGET) works for a city that has since lost its page, so nobody is stuck following a city they cannot open.- All three answer
{ "data": <follow block> }, the state after the call:
{ "data": { "following": true, "digest": true, "instant": false, "follower_count": 9, "friends": [], "friend_count": 0 } }GET /me/city-follows answers { data: [{ city: { slug, name, label, photo_url, has_page }, digest, instant, created_at }], show_followed_cities_to_friends }. The privacy switch is changed with PATCH /users/{id} (show_followed_cities_to_friends: false).
What a follower receives
- Weekly digest (
digest): on Mondays, from 9am city time, the verified Fundlies of the last 7 days the person has not heard about yet and the Fundlies fully funded in those days. Nothing new means no email. - Instant alert (
instant): an email when a Fundly in the city is approved. One raised between 22:00 and 07:00 city time waits until 07:00. - At most 3 city emails per person in any 24 hours (an alert over the cap is dropped, and the Fundly still reaches the digest), one digest per person and city a week, and each Fundly is announced to a person once, from any city, by either kind of email. The account's email preferences apply.
Every city email carries a one-click opt-out. Its token comes from the email and needs no session; integrations normally never call these:
| Endpoint | Purpose |
|---|---|
GET /cities/unsubscribe?token=&kind= | Reads only (mail scanners prefetch links): an HTML page with a button, or { data: { city, kind, digest, instant } } when the client asks for JSON. |
POST /cities/unsubscribe?token=&kind= | Turns that city's digest (kind=digest, the default) or alerts (kind=instant) off and keeps the follow. Idempotent. JSON for a mail client; a browser form is sent on to Settings with a 303. |
An unknown token is a 404 (code: "NOT_FOUND").
Languages
?lang=en|ru|uk|es on GET /cities/{slug} (else the fundlyhub_language cookie, else Accept-Language) gives the campaign cards their translated title and summary where a translation exists. A snapshot that redirects to Apple Maps passes the reader's language on as lang. The index, the map dots and the follow endpoints carry no translated text.
Errors
| Status | When |
|---|---|
400 | { "error": "Invalid sort", "code": "VALIDATION_ERROR", "allowed": [...] } for an unknown sort, area or scope; or a follow switch that is not a boolean. |
401 | A follow endpoint without credentials. |
404 | CITY_NOT_FOUND: an unknown or malformed slug, or a city without a page (the page, its snapshot, PUT follow). |
429 | Rate limited. |
503 | MAPKIT_NOT_CONFIGURED from GET /maps/token. |
500 | { "error": "Internal server error" }. |
Rate limits
- The public reads (
GET /cities,/cities/mapand its snapshot,/cities/{slug}and its snapshot,GET /maps/token) take the public limiter, 300 a minute per IP, and skip the global one.GET /cities/unsubscribetakes the public limiter and the global 100 a minute per IP as well, so 100 is its ceiling. PUTandDELETE /cities/{slug}/followtake the authenticated limiter: 100 a minute per account.POST /cities/unsubscribetakes the auth limiter: 10 a minute per IP.
See Rate Limits.
Related
- Fundraisers: a Fundly's detail read carries
city, its city block (slug,label,fundlies,donors,has_page, …), while the Fundly is verified. Link its location to the city page only whenhas_pageis true.GET /fundraisers/citiesis a different list, the Discover picker of cities with active campaigns, by the city each campaign is in. - Communities
GET /leaderboard?city=<slug>narrows the leaderboard to one city.- Cities reference