Include Nearest Obersation Station URL in /points

[nattaylor]

In order to avoid a subsequent call to https://api.weather.gov/gridpoints/{wfo}/{x},{y}/stations, I wish calls to https://api.weather.gov/points/{point} included a property nearestObservationStation that was the first result from the call to the stations endpoint.

For my simple personal weather app, I always want the current observation and forecast for a location. I respect the cache-control headers and only refresh the stations list weekly, but I'd prefer to avoid this step altogether (since it complicates my code.)

I will next add location awareness/configuration to my app, so the app will be less likely to have a cached version and sometimes the stations call is quite slow so it would be great to avoid it.

curl -w '%{time_total}' -o /dev/null -s 'https://api.weather.gov/gridpoints/GYX/71,56/stations'
13.338845

Still, I love the new API. It's been mostly easy to work with!

So specifically for a response like below I propose the addition of "nearestObservationStation": "https://api.weather.gov/stations/KBOS"

https://api.weather.gov/points/42.3755,-71.0368
{
    "@context": [
        "https://geojson.org/geojson-ld/geojson-context.jsonld",
        {
            "@version": "1.1",
            "wx": "https://api.weather.gov/ontology#",
            "s": "https://schema.org/",
            "geo": "http://www.opengis.net/ont/geosparql#",
            "unit": "http://codes.wmo.int/common/unit/",
            "@vocab": "https://api.weather.gov/ontology#",
            "geometry": {
                "@id": "s:GeoCoordinates",
                "@type": "geo:wktLiteral"
            },
            "city": "s:addressLocality",
            "state": "s:addressRegion",
            "distance": {
                "@id": "s:Distance",
                "@type": "s:QuantitativeValue"
            },
            "bearing": {
                "@type": "s:QuantitativeValue"
            },
            "value": {
                "@id": "s:value"
            },
            "unitCode": {
                "@id": "s:unitCode",
                "@type": "@id"
            },
            "forecastOffice": {
                "@type": "@id"
            },
            "forecastGridData": {
                "@type": "@id"
            },
            "publicZone": {
                "@type": "@id"
            },
            "county": {
                "@type": "@id"
            }
        }
    ],
    "id": "https://api.weather.gov/points/42.3755,-71.0368",
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            -71.036799999999999,
            42.375500000000002
        ]
    },
    "properties": {
        "@id": "https://api.weather.gov/points/42.3755,-71.0368",
        "@type": "wx:Point",
        "cwa": "BOX",
        "forecastOffice": "https://api.weather.gov/offices/BOX",
        "gridId": "BOX",
        "gridX": 71,
        "gridY": 77,
        "forecast": "https://api.weather.gov/gridpoints/BOX/71,77/forecast",
        "forecastHourly": "https://api.weather.gov/gridpoints/BOX/71,77/forecast/hourly",
        "forecastGridData": "https://api.weather.gov/gridpoints/BOX/71,77",
        "observationStations": "https://api.weather.gov/gridpoints/BOX/71,77/stations",
        "relativeLocation": {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -71.031347999999994,
                    42.396824000000002
                ]
            },
            "properties": {
                "city": "Chelsea",
                "state": "MA",
                "distance": {
                    "value": 2413.0339329283001,
                    "unitCode": "unit:m"
                },
                "bearing": {
                    "value": 190,
                    "unitCode": "unit:degrees_true"
                }
            }
        },
        "forecastZone": "https://api.weather.gov/zones/forecast/MAZ015",
        "county": "https://api.weather.gov/zones/county/MAC025",
        "fireWeatherZone": "https://api.weather.gov/zones/fire/MAZ015",
        "timeZone": "America/New_York",
        "radarStation": "KBOX"
    }
}

[KTibow]

Yes, it does complicate your code, but this is heavily documented and it would also complicate the code inside of the API.
You can run your own server that basically acts as a proxy (1 call to your server makes 2 calls to the original API). In that case you can cache stuff too.
Or you can just make a gigantic list of all stations available, and then you can use your own code to choose which one.

[nattaylor]

Ok. It seemed worth asking. Can you link me to the heavy documentation? All I am aware of is https://www.weather.gov/documentation/services-web-api#/ which is pretty light.

I would advocate for more complicated API server code so that all the clients can be simpler.

The proxy you describe would still include the latency of the API call (13 seconds in my example) on the first call.

I hadn't contemplated caching the nationwide station list and then calculating the distance, but I may go that way. Thanks for the idea.

[scadergit]

The API was heavily influenced by how the new foreast (v3) would need data. In this scenario, it needed all possible observation stations to apply business rules based on quality of observation data from MADIS. The new foreast has been on hold until infrastructure can improve the latency of the endpoints, including /points, which needs to be very fast. The challenge with /points is that it makes several calls to gather all the point-related information, so the infrastructure upgrades will likely imporve this endpoint the most. @KTibow is correct, the API was designed for proxy caching and performance, but we'll consider all suggestions because a lot has already changed since it was designed for forecast several years ago.

[nattaylor]

Thanks for the info Jared! Much 🙌 as always for the open, free, excellent APIs!