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. |
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
|
|
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
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. |
None
|
lead
|
int | None
|
One lead time in hours ( |
None
|
truth_source
|
str | None
|
What the forecasts were checked against, e.g. |
None
|
region
|
str | None
|
One region. |
None
|
metric
|
str | None
|
One metric, e.g. |
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; |
Raises:
| Type | Description |
|---|---|
ValueError
|
|
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 |
None
|
zone
|
Filter | None
|
NWS zone (UGC) code(s), e.g. |
None
|
event
|
Filter | None
|
Event name(s), e.g. |
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
|
|
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
|
ForbiddenError
|
The key lacks |
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 |
APIError
|
The batches came from different reference vintages (the data was swapped mid-lookup; ask again). |