Reducing Output

The API includes two primary methods of reducing the amount of output from the API. The primary method is using the limit/plimit parameters to control the number of elements returned. Additionally, the fields parameter can be used to reduce the types of elements that are returned.

Using the limit/plimit parameters

The limit parameter allows you to control the number of primary elements returned by the API, while the plimit parameter allows you to control the number of sub elements returned, often used within a periods object. The default for the limit parameter is normally a value of one (1).

One use case for the limit parameter is to obtain the five closest locations based on population. For example, the following query will return the 5 cities with the highest population within a 50 mile radius of Minneapolis, MN, descending by population:

/places/within?p=minneapolis,mn&radius=50miles&sort=pop:-1&limit=5

Another use case would be to obtain the 5 closest observations within 50 miles to the zip code 55403:

/observations/closest?p=55403&radius=50miles&limit=5

A use case for the plimit parameter would be to obtain the 5 most recent observations for closest observation station to Minneapolis, MN:

/observations/recent/minneapolis,mn?plimit=5

A use case for combining the limit and plimit parameters would be to obtain the two closest observations to Minneapolis, MN (limit), and then return the 5 most recent observations for each of those reporting stations (plimit):

/observations/recent/minneapolis,mn?plimit=5&limit=2

Using the fields parameter

By default the Weather API will return the complete dataset for each endpoint request as defined in the respective endpoint documentation. However, oftentimes only a portion of the complete dataset is required by an application which is where the fields parameter is useful. The fields parameter allows you to control the output by passing a comma-separated list of the required properties you want returned for each object within the dataset.

For example, your application only needs the observed temperature in degrees Fahrenheit, the primary weather type and weather icon. Using dot-notation to indicate these properties, the following could be utilized:

/observations/minneapolis,mn?fields=ob.tempF,ob.weather,ob.icon

which would return the following result:

{
   "success":true,
   "error":null,
   "response":{
      "ob":{
         "tempF":19,
         "weather":"Clear",
         "icon":"sunnyn.png"
      }
   }
}

Another use case would be to return only a forecast period's timestamp, minimum and maximum temperatures for the 7-day forecast for Minneapolis, MN:

/forecasts/minneapolis,mn?fields=periods.timestamp,periods.minTempF,periods.maxTempF

In this example, since periods is an array, the timestamp, minTempF, and maxTempF properties will be returned for each array element in the forecast.

which would return the following result:

{
   "success":true,
   "error":null,
   "response":[
      {
         "periods":[
            {
               "timestamp":1354017600,
               "minTempF":14,
               "maxTempF":37
            },
            {
               "timestamp":1354104000,
               "minTempF":18,
               "maxTempF":34
            },
            {
               "timestamp":1354190400,
               "minTempF":21,
               "maxTempF":37
            },
            {
               "timestamp":1354276800,
               "minTempF":27,
               "maxTempF":37
            },
            {
               "timestamp":1354363200,
               "minTempF":32,
               "maxTempF":45
            },
            {
               "timestamp":1354449600,
               "minTempF":32,
               "maxTempF":41
            },
            {
               "timestamp":1354536000,
               "minTempF":36,
               "maxTempF":46
            }
         ]
      }
   ]
}