API field definitions and query parameters

[jimfenton]

API field definitions
I'm working on an application that would like to retrieve primarily alerts from the API. I have collected some samples of output data from the online "try it out" tool (thanks for that!) but I'm struggling to understand what some of the field values mean. For example, the definitions of category, severity, certainty, and urgency. Is there a descriptive document of the fields and possible values anywhere?

Query parameters
I'm also trying to find the most efficient (and lowest overhead) method of making queries. One thought I had was to minimize redundant requests for multiple requests in the same proximity by converting latitude/longitude to zones and making one request for a number of zones. But I'm concerned that this may not get some alerts that may not be categorized by zone. I notice that flood warnings and perhaps tornado warnings are described by latitude and longitude and perhaps not by zone. Is this correct? What's the best way to do my queries that will minimize load on the API? This is not an immediate problem but I'd like to design my application well.

[StephenClouse]

1. Just about everything in alerts originates from the OASIS Common Alerting Protocol. Indeed, the original source of the alerts is NWS's CAP feed.
2. Polygon-based warnings should still show up in queries for the zones that contain them.

[JJKraw]

I do alert fetches at a per-state granularity, e.g.

https://api.weather.gov/alerts/active/area/MA

and cache the results. That way it only takes one fetch for all the zones/counties in a state.

All alerts will contain the affected codes (zones and/or counties) in under geocode/UGC (just the zones) and affectedZones (URLs for the zones/counties). Note that certain alerts are only issued for the county codes, particularly the ones coming from the storm prediction center, like tornado/severe thunderstorm watches. Flood warnings also have county codes from what I've observed (see Carolinas right now).

Hope this helps.

[jimfenton]

Thanks, Stephen and JJ. Fetching by state also seems like a good approach; I hadn't caught that there are both county zones and forecast zones. I'm sure there are other things I'm missing, but this should be enough to get started.

[JJKraw]

There are also fire zones. In some places they map one-to-one with the forecast zones and have the same identifier. Other places they are different.