An explanation of how to invoke server side filtering of response data.
Depending on the application, a user might choose to limit the amount of data returned in an API response.
While it is of course always possible to filter the response data on the client side, specifying that the server should filter data before sending a response has the added benefit of limiting the total response size.
To support server side filtering, both the Weather Forecast Point API and the Weather Forecast Optimized Point API provide an X-Fields header option. The value of this header can be used to specify which fields should be returned by the API.
For example:
- To request only the air_temperature and wind_speed fields from the Weather Forecast Optimized Point API, the X-Fields header value should look like this:
-
{data{values{air_temperature,wind_speed}}}Notice that in this case, we are only specifying data value fields. Therefore, no additional information (such as times or location) will be provided. Here is an example of partial output from such a filter:
{
"data": [
{
"values": {
"air_temperature": 290.37222222222226,
"wind_speed": 6.173333333333334
}
},
{
"values": {
"air_temperature": 290.9277777777778,
"wind_speed": 6.173333333333334
}
},
...
-
- To request wind_gust values and associated times from the Basic bundle through the Weather Forecast Point API, the X-Fields header value should look like this:
-
{data{times,values{wind_gust}}}Unlike the previous example, this X-Fields header is explicitly specifying that times should be included in addition to the filtered values. Here is an example of partial output from such a filter:
{
"data": [
{
"times": {
"issuance_time": "2020-04-29T00:00:00+00:00",
"valid_time": "2020-04-29T00:00:00+00:00"
},
"values": {
"wind_gust": 13.1999998092651
}
},
{
"times": {
"issuance_time": "2020-04-29T00:00:00+00:00",
"valid_time": "2020-04-29T01:00:00+00:00"
},
"values": {
"wind_gust": 13.3000001907349
}
},
...
-
- Finally, it is also possible to use the X-Fields header to only filter returned data values while maintaining the structure of a standard API response. In this case, the top-level meta field should be explicitly specified, along with the location, times, and values keys under the top-level data field. Here is an example for the Agricultural bundle in the Weather Forecast Point API that only returns soil moisture data values, while maintaining the standard API response format:
-
{meta,data{location,times,values{soil_moisture_0-10cm,soil_moisture_10-40cm,soil_moisture_40-100cm,soil_moisture_100-200cm}}}Here is an example of partial output from such a filter:
{
"meta": {
"unit_system": "si",
"forecast": "Spire Operational Forecast"
},
"data": [
{
"location": {
"coordinates": {
"lat": 42.32717,
"lon": -91.62078
}
},
"times": {
"issuance_time": "2020-04-29T00:00:00+00:00",
"valid_time": "2020-04-29T00:00:00+00:00"
},
"values": {
"soil_moisture_0-10cm": 0.293999999761581,
"soil_moisture_10-40cm": 0.295000016689301,
"soil_moisture_40-100cm": 0.300000011920929,
"soil_moisture_100-200cm": 0.307000011205673
}
},
{
"location": {
"coordinates": {
"lat": 42.32717,
"lon": -91.62078
}
},
"times": {
"issuance_time": "2020-04-29T00:00:00+00:00",
"valid_time": "2020-04-29T01:00:00+00:00"
},
"values": {
"soil_moisture_0-10cm": 0.293000012636185,
"soil_moisture_10-40cm": 0.295000016689301,
"soil_moisture_40-100cm": 0.300000011920929,
"soil_moisture_100-200cm": 0.307000011205673
}
},
...
-