Files
Every published file, what it holds and where it lives. Each format has a version and a JSON Schema.
Formats version 1 · data rules 1.95
Every file
Every file is one JSON object with the same five fields:
| Field | Type | Meaning |
|---|---|---|
id | string | The file's path from the API root |
kind | string | The format's name, such as species |
format | string | The format and its version, such as county-weekly/1.0 |
provenance | object | Sources, licences, GBIF download DOIs, method, taxonomy, boundaries, ranges, protection, code and run |
data | object | The content, as each format sets out |
Every listed field is always present: a value that does not apply is null, and an empty list is []. Weekly lists hold 53 values, weeks 1 to 53.
County and state results
county-weekly/1.0 and state-weekly/1.0 share these fields in data:
A result pools complete calendar years only: from pooled_from in methods.json through the last year that ended before the release. Records from the release's own year are stored but not counted until that year ends, so every week has the same years behind it. pooled_from moves forward one year each new year. Records before it are kept but not counted.
| Field | Type | Meaning |
|---|---|---|
area | string | us-oh for a state, a Census GEOID such as 39049 for a county |
species_key | string | The species in the shared taxonomy |
included_records | integer | Records counted, over all weeks |
contributing_years | integer | Calendar years with at least one counted record |
thresholds | object | The minimum records and years the method requires |
weekly | object | Two lists of 53: records counted, and years contributing |
season | integer[] | Early, middle and late weeks, or [] when withheld |
season_withheld | string | null | year-round, two-seasons, one-year or precision; null otherwise |
effort | integer[53] | Records of all species counted in the area each week |
limits | string | The fixed note on what results do not show |
{
"id": "releases/2026-11-13/results/us-oh/39153/32NKH.json",
"kind": "county-weekly",
"format": "county-weekly/1.0",
"provenance": { "release": "2026-11-13", "method": "seasonal-3", … },
"data": {
"area": "39153",
"species_key": "32NKH",
"included_records": 312,
"contributing_years": 6,
"thresholds": { "records": 20, "years": 5 },
"weekly": { "records": [0, 0, …], "years": [0, 0, …] },
"season": [14, 16, 19],
"season_withheld": null,
"effort": [410, 388, …],
"limits": "These results show when people recorded a species, …"
}
}All files
Paths are inside releases/<release>/ unless they are at the top: current.json, releases.json, terms.json and photos/, which sits beside the releases. Each format links its schema.
| File | Format | Holds |
|---|---|---|
current.json | current/1.0 | The current release |
releases.json | releases/1.0 | Every release, its status and DOI |
terms.json | terms/1.1 | Licence and what it covers, how to cite, credit, contact |
manifest.json | manifest/2.0 | Every file with its SHA-256 and size; counts; how many parts it has |
manifest/<n>.json | manifest/2.0 | The rest of that list, when it is too large for one file |
notes.json | notes/1.0 | Results added, changed and removed; key changes; corrections |
catalogue.json | catalogue/1.3 | Every species with a result |
species/<species_key>.json | species/1.6 | One species, its names and every area with a result |
slugs.json | slugs/1.0 | Page slugs and redirects |
groups.json | groups/1.0 | The browse groups |
search/index.json | search/1.1 | Every name, for search on the device |
regions/<state>.json | region/1.0 | A state's areas, their species and effort |
results/<state>/<species_key>.json | state-weekly/1.0 | A state result, as above |
results/<state>/<county>/<species_key>.json | county-weekly/1.0 | A county result, as above |
attribution/<state>/[<county>/]<species_key>.json | attribution/1.0 | Source credit for each result |
nearby/<state>/<county>.json | nearby/1.0 | Each species' Nearby label for every week |
methods.json | methods/1.0 | The method and its numbers |
sources.json | sources/1.0 | Each source, its licence and credit |
places/<state>/boundaries.json | boundaries/1.0 | County outlines for maps |
postal/us/<prefix>.json | postal/1.0 | ZIP codes and their counties |
schemas/<kind>-<major>.json | None | A JSON Schema for each format, below |
archive.tar.gz | None | Every other file of the release, in one download |
photos/<role>/<photo>-<width>.<format> | None | Species photos, beside the releases, each with its own licence |
No file is larger than 500 KB compressed. A larger one is split into shards numbered from 0, such as catalogue/0.json and catalogue/1.json, all listed in the manifest, and the unsplit file is then not published. current, terms, methods, state-weekly and county-weekly files are never split.
The manifest is split too when it is too large, but its first part always stays at manifest.json, so it can always be found. The rest follow as manifest/1.json, manifest/2.json and so on, and its parts says how many there are.
archive.tar.gz holds every file of the release except the manifest's parts and itself, at the same paths. The manifest lists it with its SHA-256 and size. Photos are not in a release, its manifest or its archive.
Adding a field is a minor version; removing or changing one is a major version. After a major change, releases carry both versions for 6 months, announced in notes.json. The newer version uses the same layout under v<major>/ inside the release, such as releases/2026-11-13/v2/results/us-oh/6MB3T.json, and keeps those paths.
Schemas
Each format and major version has a JSON Schema 2020-12 at schemas/<kind>-<major>.json inside every release, such as schemas/county-weekly-1.json. They are copied unchanged from the @openphenology/api package.