Here we provide detailed descriptions of the following feeds:

• The 5,000 UK locations three hourly forecasts capabilities feed
• 5,000 UK locations three hourly forecasts data feed
• Information on the 5,000 UK locations site list feed can be found here.

The 5,000 UK locations three hourly forecasts capabilities feed

Description of data feed

The capabilities data feed provides a summary of the timesteps for which results are available for the 5,000 UK locations three hourly forecast data feed. You can use this data feed to check that the timestep you are interested in is available before querying the relevant web service, or calling the relevant JavaScript API method, to get the data. In this way you can minimise the number of redundant calls that have to be made.

Accessing the feed via its web service

Description of web service

The capabilities web service returns the output of the capabilities data feed in either XML or JSON format. It is recommended that you query the capabilities web service to check whether the forecasts have been updated when querying for new data from the 5,000 UK locations three hourly forecast web service rather than calling the 5,000 UK locations three hourly forecast web service repeatedly, as this reduces the amount of data that has to be transferred, enhancing the user experience.

Possible use cases for this web service with example URLs

The 5,000 UK locations three hourly forecast capabilities web service is used to check which timesteps are currently available from the 5,000 UK locations three hourly forecast data feed. You should set the data format in the URL to specify whether the web service should return XML or JSON, and include your API key in the query string.

1. You would like to know which timesteps are available for the three hourly forecast data feed in XML format. In this case you would set the resource category to wxfcs, the temporal resolution to 3hourly, and the data type to xml:
   
   Example: to obtain capabilities for the three hourly forecast data feed:
   
   http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/xml/capabilities?res=3hourly&key=<APIkey>
   
   The above example would return around 40 timesteps in XML format, resulting in a file size of approximately 1.5 kB
2. You would like to know which timesteps are available for the three hourly forecast data feed in JSON format. In this case you would set the resource category to wxfcs and the temporal resolution to 3hourly, and the data type to json:
   
   Example: to obtain capabilities for the three hourly forecast data feed:
   
   http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/json/capabilities?res=3hourly&key=<APIkey>
   
   The above example would return around 40 timesteps in JSON format, resulting in a file size of approximately 1.6 kB

Example of XML and JSON responses

The following examples show a typical result of a call to the capabilities web service requesting a complete list of timesteps available from the 5,000 UK locations three hourly forecast web service.

XML

The XML that follows is a representative response to a call to the following URL, with a valid key:

http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/xml/capabilities?res=3hourly&key=<APIkey>

JSON

The JSON that follows shows the structure of a representative response to a call to the following URL, with a valid key:

http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/json/capabilities?res=3hourly&key=<APIkey>

Anatomy of responses

The XML and JSON responses produced by this web service are identical in terms of their high level structure and the information they represent. Each contains a single Resource object (or node in XML), defined as follows:

Resource

A Resource object defines the current capabilities of the relevant web service, and contains the following attributes:

• type: This corresponds to the resource type of the web service for which the capabilities have been returned
• res: This refers to the temporal resolution of the web service for which the capabilities have been returned. This is set to the temporal resolution specified in the query
• dataDate: This describes the date and time at which the data was last updated, expressed according to the ISO 8601 combined date and time convention

The value of the Resource object comprises a single TimeSteps object, which in turn contains a set of TS objects. The value of each TS object (or each element in the TS array in the JSON representation) provides a description of a single available timestep, expressed according to the ISO 8601 combined date and time convention.

  5,000 UK locations three hourly forecasts data feed

Accessing the feed via its web service

Description of web service

This provides access to three hourly forecast data from the Met Office for each of the roughly 5,000 sites for which the Met Office provides data. The forecast data is provided for time steps that are three hours apart, starting with the time at which the forecast was last run, and ending approximately five days later (meaning that approximately 40 forecast timesteps are available for each site). The data provided by the web service is updated on an hourly basis, and at any given point in time the exact set of timesteps that are available can be obtained using the capabilities web service. For a full list of the 5,000 sites, call the 5,000 UK locations site list data feed.

Possible use cases for this web service with example URLs

Since this web service supplies forecast data, whenever this web service is used the resource category field in the URL should be set to wxfcs, and, as is the case for all web services, you should also set the data format in the URL to specify whether the web service should return XML or JSON, and include your API key in the query string.

1. You would like a complete list of the forecasts for a specified location at each available timestep. In this case you specify the location ID explicitly in the location field.
   
   Example: to obtain forecasts for a specified location at all available times in XML format:
   
   http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/xml/[LocationID]?res=3hourly&key=<API key>
   
   The above example would return around 40 forecast timesteps in XML format, resulting in a file size of approximately 4 kB
2. You would like a complete list of the forecasts for every location in the UK at a particular time. In this case you specify the time explicitly in the query string, and set the location field in the URL to all.
   
   Example: to obtain forecasts for every location in the UK at a particular time in XML format:
   
   http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/xml/all?res=3hourly&time=2011-11-10T18Z&key=<API key>
   
   The above example would return around 5,000 forecast timesteps in XML format, resulting in a file size of approximately 1.4 MB
3. You would like a complete list of the forecasts for every location in the UK at each available timestep. In this case the arguments specified are the same as those specified in the third use case for this web service, except that the time is not specified.
   
   Example: to obtain forecasts for every location in the UK at all available times in XML format:
   
   http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/xml/all?res=3hourly&key=<API key>
   
   The above example would return around 200,000 forecast timesteps in XML format, resulting in a file size of approximately 23 MB

Example of XML and JSON responses

The following examples show a typical result of a call to the 5,000 UK locations three hourly forecast web service requesting a complete list of the forecasts for Heathrow at each available timestep. The following section provides a detailed description of the structure and content of the responses.

XML

The XML that follows is a representative response to a call to the following URL, with a valid key:

http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/json/3772?res=3hourly&key=<APIkey>

JSON

The JSON that follows shows the structure of a representative response to a call to the following URL, with a valid key:

http://datapoint.metoffice.gov.uk/public/data/val/wxfcs/all/json/capabilities?res=3hourly&key=<APIkey>

Anatomy of responses

The XML and JSON responses produced by this web service are identical in terms of their high level structure and the information they represent. Each contains a single SiteRep object (or node in XML), defined as follows:

SiteRep

The SiteRep object comprises a single Wx object and a single DV object. Each of these objects is described below.

Wx

The Wx object comprises a number of Parm objects, defined below.

Param

A Param object contains the definition of one of the attributes in a single forecast (Rep) object, and contains the following attributes:

• units:  This describes the unit in which the attribute value is represented.
• name: This refers to the attribute name in the Rep object

The value of the Param object($ in the JSON representation) provides a textual description of what the corresponding attribute represents in the corresponding Rep object.

DV

The DV object contains the following attributes:

• type:  This describes the type of data that the web service returns. For this web service the value is always Forecast
• dataDate: This describes the date and time at which the forecast was run, expressed according to the ISO 8601 combined date and time convention

The value of the DV object comprises a set of Location objects, as described below.

Location

A Location object contains the following attributes:

• continent: This describes the continent in which the location is located
• country: This describes the country in which the location is situated
• name: This provides the name of the location
• lon: This provides the longitude of the location
• lat: This provides the latitude of the location
• i: This provides the ID of the location

The value of a Location object comprises a set of Period objects, as described below.

Period

A Period object contains the following attributes:

• val: This describes the date of the day represented by the Period object in ISO 8601 format
• type: This describes the type of period that the web service covers. For this web service the value is always 'Day'

The value of a Period object comprises a set of Rep objects, as described below.

Rep

A Rep object contains a single forecast, and contains the elements listed in the table below. The units for each of these elements are described in Unit definitions.

• U: This gives the Maximum Uv Index
• W: This gives the Weather Type
• V: This gives the Visibility
• T: This gives the Temperature
• S: This gives the Wind Speed
• Pp: This gives the Precipitation Probability
• H: This gives the Screen Relative Humidity
• G: This gives the Wind Gust
• F: This gives the Feels Like Temperature
• D: This gives the Wind Direction

The value of a Rep object ($ in the JSON representation) denotes the number of minutes after midnight GMT on the day represented by the Period object in which the Rep object is found.