Skip to content

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 sectionOperationsAbout
Cities12The `/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 ​

WhatRule
donorsExact from the first donor (signed in, guest or anonymous); null when there are none.
follow.follower_countShown at 5 followers or more; null below.
gift_destinations, backedShown at 5 donors or more; null below.
Donors themselvesNever listed by city, to anyone.
follow.friendsAt 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):

FieldNotes
slug, name, region, countrycountry is ISO 3166-1 alpha-2; in the US region is the state code.
labelWhat to print: "Sacramento, CA" in the US, "Kyiv, Ukraine" elsewhere.
photo_urlThe square city photo, or null.
lat, lngThe city's point. Pass it as near to GET /fundraisers for the campaigns around it.
fundlies_active, fundlies_fundedVerified Fundlies started here that are live now, and that reached their goal.
donorsDistinct donors who live here, or null.
raised_centsWhat the verified Fundlies started here raised.
has_pageWhether 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 ​

EndpointAuthReturns
GET /citiesOptionalThe index: a page of cards, platform totals and "near you".
GET /cities/{slug}OptionalOne city page.
GET /cities/mapPublic{ points }, one dot per city.
GET /cities/map/snapshot · GET /cities/{slug}/snapshotPublicThe map as an image.
GET /maps/tokenPublicThe 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.

QueryNotes
qCase-insensitive substring of the city's name or its metro's name. Trimmed and cut to 80 characters; % and _ are literal.
sortactive (default): most live Fundlies first, then most donors, then most raised, then by name. az: by name. Anything else is a 400.
areaall (default), us or intl. Anything else is a 400.
near<lat>,<lng>, for near_you only; it does not filter the list.
limit1–500, default 24. A missing, zero, negative or non-numeric value is 24; a larger one is 500.
offsetDefault 0.
bash
curl "https://api.fundlyhub.org/api/v1/cities?sort=active&limit=1"
json
{
  "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"
}
  • total counts the cities that match q and area; page through them with offset.
  • totals is platform-wide and ignores q and area: 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, and donors (people who live in a city, each counted once however many cities they gave from).
  • near_you is the nearest city with a page within 100 miles of a point, or null. The point is near when you send one. Without near it 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 malformed near is not an error: it is ignored and only the profile city is tried.
  • map_version changes whenever any city changes. Add it to the snapshot URLs as v, 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:

json
{
  "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.)

FieldHolds
cityThe 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).
statsfundlies_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_helpUp 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_fundedUp to 12 verified Fundlies here that reached their goal, most recently funded first.
communitiesEvery listed community placed here, as directory cards, featured first, then the most members. See Communities.
nonprofitsEvery verified non-profit placed here, as directory cards; a card with is_church: true is a church.
ambassadorsUp to 12 public profiles here holding the ambassador role, by money driven: name, avatar_url, handle, driven_cents, fundlies_organized.
nearbyUp to 8 other cities with a page: the same metro first, then the nearest within 150 miles.
gift_destinationsThe 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.
followThe 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:

EndpointFrameDefault size
GET /cities/map/snapshot?scope=us|worldThe lower 48 (us, the default) or the world1152 × 480
GET /cities/{slug}/snapshotAbout 27 km across, centred on the city; 404 without a page640 × 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 ​

EndpointAuthPurpose
GET /cities/{slug}/followSigned inThe caller's follow block.
PUT /cities/{slug}/followSigned in{ "digest"?: boolean, "instant"?: boolean }: follow, or change the switches.
DELETE /cities/{slug}/followSigned inUnfollow.
GET /me/city-followsSigned inEvery city the caller follows, newest first.

Following needs an account; there is no anonymous mailing list.

  • PUT is 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 both false silences a city without unfollowing it. A switch that is not a boolean is a 400, and a city without a page is a 404.
  • DELETE is idempotent, and it (like GET) 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:
json
{ "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:

EndpointPurpose
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 ​

StatusWhen
400{ "error": "Invalid sort", "code": "VALIDATION_ERROR", "allowed": [...] } for an unknown sort, area or scope; or a follow switch that is not a boolean.
401A follow endpoint without credentials.
404CITY_NOT_FOUND: an unknown or malformed slug, or a city without a page (the page, its snapshot, PUT follow).
429Rate limited.
503MAPKIT_NOT_CONFIGURED from GET /maps/token.
500{ "error": "Internal server error" }.

Rate limits ​

  • The public reads (GET /cities, /cities/map and 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/unsubscribe takes the public limiter and the global 100 a minute per IP as well, so 100 is its ceiling.
  • PUT and DELETE /cities/{slug}/follow take the authenticated limiter: 100 a minute per account.
  • POST /cities/unsubscribe takes the auth limiter: 10 a minute per IP.

See Rate Limits.

  • 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 when has_page is true. GET /fundraisers/cities is 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

Built with VitePress