The CityFunIndex API

The endpoints

The data is a licensed product. Every programmatic and bulk pull runs through a keyed, versioned endpoint set at https://cityfunindex.com/v1 — the same scores the site runs on, plus the raw measured value behind every factor. The website itself stays free to browse; the API is the paid way to build on the data.

• /v1/city/{slug} — one city in full, with the complete factor breakdown and raw values.
• /v1/cities — the whole index in one response. Business+
• /v1/dataset.csv — every city flattened to a single CSV. Business+
• /v1/usage — your plan, allowance and usage this period. Never metered.

Quick start

Provision a key with any paid plan, then send it on every request — Authorization: Bearer <key> or X-API-Key. Each endpoint is a plain HTTPS GET that returns JSON. The same call in four common runtimes:

# one city in full — every factor score AND its raw measured value
curl -H "Authorization: Bearer $CFI_KEY" \
  https://cityfunindex.com/v1/city/nashville-tn

// One city's full record, in any modern JS runtime. Keep the key
// server-side — it is a credential, never expose it in browser code.
const res = await fetch(
  'https://cityfunindex.com/v1/city/nashville-tn',
  { headers: { Authorization: `Bearer ${process.env.CFI_KEY}` } },
);
if (!res.ok) {
  throw new Error(`fun score fetch failed: ${res.status}`);
}
const city = await res.json();
console.log(`${city.name}: ${city.universal_score} (${city.category})`);

# Pull one city's full record. Requires `pip install requests`.
import os, requests

res = requests.get(
    "https://cityfunindex.com/v1/city/nashville-tn",
    headers={"Authorization": f"Bearer {os.environ['CFI_KEY']}"},
    timeout=10,
)
res.raise_for_status()
city = res.json()
print(f"{city['name']}: {city['universal_score']} ({city['category']})")

// Bulk index — Business and Enterprise plans only. Node 18+ ships fetch.
const res = await fetch('https://cityfunindex.com/v1/cities', {
  headers: { Authorization: `Bearer ${process.env.CFI_KEY}` },
});
const cities = await res.json();

// Top ten by Fun Score.
cities
  .sort((a, b) => b.universal_score - a.universal_score)
  .slice(0, 10)
  .forEach((c, i) => console.log(
    `${(i + 1).toString().padStart(2)} ${c.name}, ${c.state}  ${c.universal_score}`,
  ));

Field-by-field reference for each endpoint follows below. Definitions for every term — Fun Score, raw composite, pillar, calibration — are in the glossary.

OpenAPI spec

Every endpoint and every field above is described in a machine-readable OpenAPI 3.1 spec. Point any generator at it — openapi-generator, Speakeasy, Kiota, Orval — to scaffold a typed client SDK in any of 40+ languages in a single command.

/api/openapi.json →

Versioning

Every published record carries an algorithm_version string. It is the contract you integrate against — when it changes, your client should treat the new bundle as a new dataset.

CityFunIndex is still in development — the live bundles carry a -dev suffix, which marks a pre-1.0 release where the algorithm shape may still change. The stability guarantees below are the policy we commit to at v1.0 (GA); until then, treat the schema as evolving and pin to the algorithm_version you tested against.

• Format. vMAJOR.MINOR.PATCH (semver). A PATCH bump is a recompute on unchanged math; a MINOR bump tightens a calibration; a MAJOR bump changes the formula or factor set.
• Stability window. Once CityFunIndex reaches v1.0 (GA), every MAJOR change will be announced at least 60 days before publication on Business and Enterprise plans, and the previous MAJOR will remain available at the same URL with a versioned suffix for one full quarter after release.
• Suffixes. A -sample suffix (e.g. v2.0.3-dev-sample) means the bundle is illustrative preview data, not the live index. Never integrate against a -sample version in production. A -dev suffix marks the current pre-1.0 build, whose schema may still change.
• Field stability. Once CityFunIndex reaches v1.0 (GA), no field will be removed and no field type will change within one MAJOR version. New fields may be added — your parser should ignore unknown keys at any stage.
• Where to track changes. Every API, data and site change is logged on the public changelog, newest first.

Errors

Error handling is HTTP-status-shaped and intentionally narrow. The metering responses (401, 403, 429) have their own table under metering & rate limits; the status codes below cover the rest.