---
title: "Published cities with place counts, areas, accent colours and city facts"
method: GET
path: "/api/cities"
---

# Published cities with place counts, areas, accent colours and city facts

`GET /api/cities`

## Request

- Base URL: `https://chinafootnotes.com`
- URL: `https://chinafootnotes.com/api/cities`
- Auth: none declared

## Response `200`

Published cities

- CityList
  - `schemaVersion` string
  - `version` string
  - `generatedAt` string, date-time
  - `notice` string
  - `total` integer, required
  - `cities` City[], required
    - `id` string, required
    - `name` string, required
    - `zh` string, required
    - `live` boolean, required
    - `preview` boolean: Only in local preview builds of unreviewed data
    - `placeCount` integer, required
    - `accent` string, required: #rrggbb
    - `accentSoft` string, required: #rrggbb
    - `tagline` string, nullable: null until written
    - `stats` object[], nullable: null until collected
      - `key` string
      - `label` string
      - `value` union
        - number
        - string
      - `unit` string, nullable
      - `source` unknown
      - `asOf` string, nullable
    - `weather` object[], nullable: 12 months, or null
      - `month` integer
      - `highC` number
      - `lowC` number
      - `icon` 'sun' | 'cloud' | 'rain' | 'snow' | 'haze' | 'null', nullable
      - `rainDays` number, nullable
      - `source` unknown
    - `areas` object[], nullable
      - `id` string
      - `name` string
      - `zh` string, nullable
      - `line` string, nullable
      - `numbers` integer[]
      - `focus` integer[]
    - `groups` object, nullable
      - `town` integer[]
      - `trips` object[]
        - `number` integer
        - `distanceKm` number, nullable
    - `bookFirst` string[]: Place ids that need booking ahead, from the place booking data
    - `arrivals` object[], nullable
      - `name` string
      - `zh` string
      - `kind` 'airport' | 'station'
      - `how` string: One-line summary
      - `routes` object[]
        - `mode` 'metro' | 'maglev' | 'rail' | 'bus' | 'taxi'
        - `text` string
        - `fare` object, nullable: Yuan; min null = up to max
          - `min` number, nullable
          - `max` number
          - `approx` boolean
        - `durationMin` integer, nullable
        - `lastService` string, nullable: HH:MM
        - `serviceHours` string: HH:MM–HH:MM
      - `caveats` object[]
        - `text` string
        - `sourceIds` string[]
      - `tips` object[]: Traveller reports, each with its evidence
        - `title` string
        - `body` string
        - `caveat` string
        - `evidence` object[]
      - `gaps` object[]: Not found yet, with the search record
        - `reason` string
        - `searched` object[]
        - `nextStep` string
      - `checkedAt` string, date
      - `sourceIds` string[]: Ids in City.sources
    - `nextStops` object[], nullable: Other cities reachable by train, listed only when that city is published in this build
      - `city` string
      - `trainTime` unknown
      - `source` unknown
    - `photo` object, nullable
      - `src` string
      - `credit` string
      - `href` string
      - `rights` string
    - `skyline` string, nullable
    - `scene` object, nullable
    - `metroColors` object, nullable: Line → [background, ink]
    - `ratings` object, nullable: Editorial ratings comparing the cities on this site; subjective, not an official ranking. plan = how early to book (shown as calendars; more = book earlier), not better or worse.
      - `history` object, required
        - `stars` number, required
        - `display` 'stars', required
        - `overview` string, required: Shown when the reader opens the rating
        - `reason` string, required: Why this rating; may repeat the overview
      - `food` object, required
        - `stars` number, required
        - `display` 'stars', required
        - `overview` string, required: Shown when the reader opens the rating
        - `reason` string, required: Why this rating; may repeat the overview
      - `cityscape` object, required
        - `stars` number, required
        - `display` 'stars', required
        - `overview` string, required: Shown when the reader opens the rating
        - `reason` string, required: Why this rating; may repeat the overview
      - `nature` object, required
        - `stars` number, required
        - `display` 'stars', required
        - `overview` string, required: Shown when the reader opens the rating
        - `reason` string, required: Why this rating; may repeat the overview
      - `shopping` object, required
        - `stars` number, required
        - `display` 'stars', required
        - `overview` string, required: Shown when the reader opens the rating
        - `reason` string, required: Why this rating; may repeat the overview
      - `plan` object, required
        - `stars` number, required
        - `display` 'calendar', required
        - `overview` string, required: Shown when the reader opens the rating
        - `reason` string, required: Why this rating; may repeat the overview
    - `images` object, nullable: City illustrations: hero (city page header), card (city card, cropped from the hero at objectPosition) and bg (home background)
      - `hero` object
        - `sizes` object[]: WebP sizes, small to large (use as srcset)
          - `src` string, required
          - `width` integer, required
          - `height` integer, required
        - `objectPosition` string
      - `card` object
        - `from` 'hero'
        - `objectPosition` string
      - `bg` object
        - `sizes` object[]: WebP sizes, small to large (use as srcset)
          - `src` string, required
          - `width` integer, required
          - `height` integer, required
        - `objectPosition` string
    - `transit` object, nullable: The city metro: how to pay and ride
      - `name` string
      - `zh` string
      - `summary` string
      - `steps` string[]
      - `fares` object: Yuan amounts and a note
      - `caveats` object[]
        - `text` string
        - `sourceIds` string[]
      - `tips` object[]: Traveller reports, each with its evidence
        - `title` string
        - `body` string
        - `caveat` string
        - `evidence` object[]
      - `checkedAt` string, date
      - `sourceIds` string[]
    - `sources` Source[]: Sources cited by arrivals, transit and notes (sourceIds)
      - `id` string, required
      - `url` string, uri, nullable, required: null only for our own checks, which have no web page: kind owner_tested (we tried it ourselves; first-hand, not official) or owner_official (the venue's own answer: method phone, onsite_sign or onsite_notice; official). accessedAt is the day we checked.
      - `title` string, required
      - `publisher` string, required
      - `kind` 'official' | 'government', required
      - `method` 'phone' | 'onsite_sign' | 'onsite_notice' | 'null', nullable: Only for kind owner_official: how we got the venue’s answer (by phone, a standing sign on site, or a temporary notice on site).
      - `contact` string, nullable: Only for method phone: who we called (venue and number).
      - `accessedAt` string, date, required
      - `publishedAt` string, date, nullable

## Other responses

- `400`: Invalid URL encoding
- `500`: Local data/service unavailable

---

[API](https://skmtc.dev/chinafootnotes/apis/china-footnotes.md) · [All operations](https://skmtc.dev/chinafootnotes/apis/china-footnotes/llms.txt) · [OpenAPI document](https://skmtc.dev/chinafootnotes/apis/china-footnotes/revisions/b0050778a942?raw)