data
What an API Gives You That a Map Does Not
Why a polygon you can test against beats a polygon you can look at, and the GeoJSON and rate limit details that decide whether the test works.
A warning polygon drawn on a map and the same polygon in an API response look like two views of one object. They are not. A map answers a question a person asks once, by looking at it. An API answers a question a program asks many times, by computing it. Those are different operations with different outputs, and the difference is not convenience.
Start with what the polygon is for. The National Weather Service upgraded warning capabilities on October 1, 2007. Before that, warnings were county-based and covered an entire county regardless of which portion of it the storm threatened. Under storm-based warnings, the polygon covers only the portion of the county actually threatened. The same handout works an example: tornado warnings in effect for Hale, Bibb, Perry, Tuscaloosa, Jefferson and Shelby counties, while the cities of Tuscaloosa, Birmingham and Calera sat outside the polygons and were therefore not under a tornado warning.
That example is the whole argument in miniature. The county name is not the answer. The geometry is the answer. And deciding whether one specific place sits inside one specific shape is a test, which has an input, an output and a record.
Looking at a shape, versus testing against it
A map renders the polygon so a person can see it. The output is a picture and the person's judgment is the result. For one address on one day that is often enough, and the handout's own worked example shows a careful reader getting the right answer by eye.
An API hands you the polygon as data. The output becomes a value per location, produced by code. Several practical things follow from that.
You can test a long list at once. Instead of reading pins off a screen and deciding which ones look inside, you run every address through the same test and get one answer each. The work scales with compute instead of attention, and attention is where eyeballing fails first. Not on the obvious interior points, but on the ones near the edge, after an hour of scrolling.
You get an answer you can reproduce. A screenshot records what somebody saw. A stored request and its response record what was asked and what came back, which is a different kind of evidence. Run the same inputs again and you either get the same result or you learn that something changed.
You get a timestamp on the pull. Warning geometry and report feeds are live products. The question is never only whether a point was inside a polygon, but whether it was inside the polygon as published at the moment you looked. A recorded pull time makes that answerable later.
And you get a boundary you can version. The polygon becomes a value you can store, compare and keep alongside the answer it produced. When somebody disputes the result six months on, you can show the exact shape you tested against instead of re-deriving it and hoping it matches.
The coordinate order that fails quietly
All of this rests on parsing the geometry correctly, and the most common mistake in point-in-polygon work produces no error at all.
In GeoJSON, a position is an array whose first two elements are longitude then latitude, with an optional third element for altitude in meters. Longitude first. Most human-facing tools, most spreadsheets and most conversation put latitude first. Swap them and nothing throws an exception. The point lands somewhere else on the planet, the test returns false, and your pipeline reports that none of the addresses were affected. A silent no-match looks exactly like a correct negative, which is why this one survives code review.
The coordinate reference system at least removes a different class of error. The default is the WGS 84 datum in decimal degrees, equivalent to CRS84, and alternative coordinate reference systems were removed in this version of the specification. There is no projection to negotiate and nothing to get wrong, which also means there is no excuse for feeding in state plane feet.
Rings, closure and the seven types
A polygon in GeoJSON is built from linear rings, and the rules are strict. A linear ring is a closed LineString with four or more positions, and the first and last positions must have identical values. A ring that is not closed is not a valid polygon. That is easier to hit than it sounds. The usual causes are building a ring from a list of vertices and forgetting to append the first one again, or rounding coordinates on output until the first and last no longer match exactly.
Winding order is softer. Exterior rings run counterclockwise and holes run clockwise, by the right-hand rule, but parsers should not reject polygons that ignore this, for backward compatibility. So you cannot rely on winding to tell you which ring is which. The structural rule does that job instead: the first ring is the exterior ring, and additional rings are interior rings, meaning holes.
One more distinction saves time in review. There are seven geometry types: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Feature and FeatureCollection are GeoJSON types but they are not geometry types. Code that switches on geometry type and expects to find Feature there is reading one level too high. And a MultiPolygon handled as a Polygon tests against only part of the shape, which again fails without complaining.
The API is built to be cached
Operational behavior is the other half of what an API gives you, and a map in a browser gives you none of it.
The NWS web API is designed for caching. The guidance is specific about where the line sits. Applications can cache a location's grid mapping, but should periodically re-check the points endpoint, because office and grid coordinates can change. That is a useful shape for any storm pipeline. The mapping from a location to whatever internal cell or office covers it is stable enough to store and too expensive to recompute on every request, and it is still not permanent. Store it, then re-check it on a schedule rather than treating it as settled forever.
There is no equivalent lever on a person looking at a screen. You cannot cache their attention, and you cannot invalidate their memory when the grid moves under them.
Rate limits are part of the design
Free services set limits, and the limits are usually the real constraint on what you can build.
The OpenStreetMap Foundation's Nominatim usage policy states an absolute maximum of 1 request per second. The unit matters more than the number: the limit applies per website or application, so all of your users' traffic combined must stay under it, not each user separately. A script that runs past a day, or runs on a schedule, drops to a cap of 4 requests per minute. The policy also requires a valid HTTP Referer or User-Agent identifying the application, and says stock user agents as set by HTTP libraries will not do.
The NWS API does not publish its rate limits, but describes them as generous for typical use, says an over-limit request returns an error you can retry once the limit resets, usually within about five seconds, and notes that proxies are more likely to hit the limit than direct clients.
Read those two together and the architecture writes itself. Caching is not an optimization here, it is a condition of access. A per-application limit means your request budget is a shared resource across every customer and every background job you run. And a retryable error with a short reset window is something to handle in code, not something to page somebody about.
What an API does not do
It does not make the underlying estimate more true.
If the polygon you are testing against came from a radar-derived product, the uncertainty in that product survives the test intact. The Severe Weather Data Inventory at NCEI states that it adds no quality control beyond archival processing, that missing data does not mean no severe weather occurred, and that much of the automatically derived data is radar-based and represents probable rather than confirmed conditions. A program that returns true for an address inside such a polygon has computed something exact about something uncertain, and the exactness belongs to the arithmetic.
That is still worth having. The point of moving from a map to an API is not better weather information. It is that the same estimate becomes testable across a long list, reproducible on demand, timestamped at the moment of the pull, and auditable against the exact geometry you used. The estimate does not improve. What improves is your ability to show what you did, and to be caught when you got it wrong.