Skip to content

Scores, advisories and ZIP codes

client.scores, client.advisories and client.zips. AsyncClient has the same methods, awaited; advisories.iter_list is driven with async for.

Scores

Model verification scores. Reach it as client.scores.

A month is "YYYY-MM" or a date/datetime (its UTC calendar month); anything else raises ValueError before a request is sent. Scores are served as computed (to_dataframe(units=...) does not apply).

get

get(model: str) -> Score

A model's current Shyft Score (shyft_score is None when none is stored).

Raises:

Type Description
ModelNotFoundError

No such model, or your key may not see it.

history

history(model: str) -> ScoreHistory

A model's score, one point per calendar month.

regions

regions(model: str) -> RegionScores

A model's score in each of the nine NCEI climate regions.

ranking

ranking(month: MonthLike) -> MonthRanking

Every model you can see, ranked by its score for one month.

Parameters:

Name Type Description Default
month MonthLike

"YYYY-MM", or a date/datetime (its UTC calendar month).

required

Raises:

Type Description
ValueError

month is not a month (nothing is sent).

badges

badges(model: str) -> ModelBadges

The slices a model beats its published rivals on, best first.

badge_headlines

badge_headlines() -> BadgeHeadlines

The headline badge of every model that holds one.

scorecard

scorecard(
    model: str,
    *,
    parameter: str | None = None,
    lead: int | None = None,
    truth_source: str | None = None,
    region: str | None = None,
    metric: str | None = None,
    month: MonthLike | None = None,
    version: str | None = None,
    limit: int | None = None,
) -> Scorecard

A model's per-slice verification scores.

Every filter is optional; Scorecard.available lists what each can take.

Parameters:

Name Type Description Default
model str

The model.

required
parameter str | None

One parameter, e.g. "temperature_2m".

None
lead int | None

One lead time in hours (0 is the analysis hour, and is sent).

None
truth_source str | None

What the forecasts were checked against, e.g. "metar".

None
region str | None

One region.

None
metric str | None

One metric, e.g. "rmse".

None
month MonthLike | None

One calendar month. Default: the API's rolling window.

None
version str | None

One model version.

None
limit int | None

At most this many entries (the API's default and cap: 5,000).

None

Returns:

Type Description
Scorecard

The scorecard; truncated is true when the API capped the entries.

Raises:

Type Description
ValueError

month is not a month (nothing is sent).

Advisories

Active advisories. Reach it as client.advisories; needs read:observations.

A filter value may not contain a comma (the API splits on commas; ValueError). A place is one 5-digit ZIP code or a list of them (every advisory covering any of those ZIPs, whole ZIPs), or (lat, lon) / a LatLon (every advisory covering that point). zone, event and source narrow further; each takes one value or a list.

list

list(
    place: AdvisoryPlace | None = None,
    *,
    zone: Filter | None = None,
    event: Filter | None = None,
    source: Filter | None = None,
    geometry: bool = False,
    limit: int | None = None,
    offset: int | None = None,
) -> AdvisoryPage

One page of active advisories.

Parameters:

Name Type Description Default
place AdvisoryPlace | None

A ZIP code, a list of ZIP codes, or (lat, lon). Default: everywhere.

None
zone Filter | None

NWS zone (UGC) code(s), e.g. "NEZ052".

None
event Filter | None

Event name(s), e.g. "Winter Storm Warning" (see types()).

None
source Filter | None

Advisory source(s). Default: every source you can read.

None
geometry bool

Include each advisory's GeoJSON shape. Shapes are large (a page can run to tens of MB): filter by place first.

False
limit int | None

Page size (the API's default 5,000, at most 10,000).

None
offset int | None

next_offset from the previous page.

None

Raises:

Type Description
ValueError

place is none of the accepted forms (nothing is sent).

ForbiddenError

The key lacks read:observations.

iter_list

iter_list(
    place: AdvisoryPlace | None = None,
    *,
    zone: Filter | None = None,
    event: Filter | None = None,
    source: Filter | None = None,
    geometry: bool = False,
    limit: int | None = None,
) -> Iterator[AdvisoryPage]

list() page after page, one request each, only as you advance it.

The set is live, so an advisory can move between pages while you read them: one already yielded is dropped from later pages.

types

types(
    place: AdvisoryPlace | None = None,
    *,
    zone: Filter | None = None,
    source: Filter | None = None,
) -> AdvisoryTypes

The event names of the active advisories (with counts), under the same filters.

get

get(
    advisory_id: str,
    *,
    geometry: bool = False,
    source: Filter | None = None,
) -> AdvisoryDetail

One advisory by its id.

Raises:

Type Description
AdvisoryNotFoundError

No active advisory has that id.

Zips

ZIP code lookups. Reach it as client.zips; needs read:observations.

lookup

lookup(codes: str | Iterable[str]) -> ZipLookup

What one or more ZIP codes cover.

Codes are de-duplicated; more than 200 are sent 200 at a time and merged into one result (zips and unknown sorted). A code the reference data does not know is listed in unknown, not raised.

Parameters:

Name Type Description Default
codes str | Iterable[str]

One 5-digit ZIP code, or several.

required

Raises:

Type Description
ValueError

A code is not five digits, or none was given (nothing is sent).

ZipLookupForbiddenError

The key lacks read:observations.

APIError

The batches came from different reference vintages (the data was swapped mid-lookup; ask again).