UK observations detailed documentation
Detailed documentation on each of the data feeds associated specifically with UK observations
Here we provide detailed descriptions of the following feeds:
UK observations capabilities feed
Description of data feed
The capabilities data feed provides a summary of the time-steps for which results are available for the UK observations data feed. You can use this data feed to check that the time-step you are interested in is available before querying the relevant web service 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 observations have been updated when querying for new data from the UK observations web service rather than calling the UK observations 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
Since the capabilities web service concerns observation data, whenever this web service is used the resource category field in the URL should be set to wxobs, 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 to know which time-steps are available for the UK observations data feed in XML format. In this case you would set the resource category to wxobs, and the data type to xml:
Example: to obtain capabilities for the UK observations data feed in XML format:
http://datapoint.metoffice.gov.uk/public/data/val/wxobs/all/xml/capabilities?res=hourly&key=<APIkey>
The above example would return around 24 time-steps in XML format, resulting in a file size of approximately 3 kB
2. You would like to know which time-steps are available for the three UK observations data feed in JSON format. In this case you would set the resource category to wxobs, and the data type to json:
Example: to obtain capabilities for the UK observations data feed in JSON format:
http://datapoint.metoffice.gov.uk/public/data/val/wxobs/all/json/capabilities?res=hourly&key=<APIkey>
The above example would return around 24 time-steps in JSON format, resulting in a file size of approximately 2 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 time-steps available from the UK observations 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/wxobs/all/xml/capabilities?res=hourly&key=<APIkey>
<?xml version="1.0" encoding="ISO-8859-1"?>
<Resource res="hourly" type="wxobs">
<TimeSteps>
<TS>2012-12-09T14:00:00Z</TS>
<TS>2012-12-09T15:00:00Z</TS>
<TS>2012-12-09T16:00:00Z</TS>
<TS>2012-12-09T17:00:00Z</TS>
<TS>2012-12-09T18:00:00Z</TS>
<TS>2012-12-09T19:00:00Z</TS>
<TS>2012-12-09T20:00:00Z</TS>
<TS>2012-12-09T21:00:00Z</TS>
<TS>2012-12-09T22:00:00Z</TS>
<TS>2012-12-09T23:00:00Z</TS>
<TS>2012-12-10T00:00:00Z</TS>
<TS>2012-12-10T01:00:00Z</TS>
<TS>2012-12-10T02:00:00Z</TS>
<TS>2012-12-10T03:00:00Z</TS>
<TS>2012-12-10T04:00:00Z</TS>
<TS>2012-12-10T05:00:00Z</TS>
<TS>2012-12-10T06:00:00Z</TS>
<TS>2012-12-10T07:00:00Z</TS>
<TS>2012-12-10T08:00:00Z</TS>
<TS>2012-12-10T09:00:00Z</TS>
<TS>2012-12-10T10:00:00Z</TS>
<TS>2012-12-10T11:00:00Z</TS>
<TS>2012-12-10T12:00:00Z</TS>
<TS>2012-12-10T13:00:00Z</TS>
</TimeSteps>
</Resource>
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/wxobs/all/json/capabilities?res=hourly&key=<APIkey>
{
"Resource": {
"res": "hourly",
"type": "wxobs",
"TimeSteps": {
"TS": [
"2012-12-09T14:00:00Z",
"2012-12-09T15:00:00Z",
"2012-12-09T16:00:00Z",
"2012-12-09T17:00:00Z",
"2012-12-09T18:00:00Z",
"2012-12-09T19:00:00Z",
"2012-12-09T20:00:00Z",
"2012-12-09T21:00:00Z",
"2012-12-09T22:00:00Z",
"2012-12-09T23:00:00Z",
"2012-12-10T00:00:00Z",
"2012-12-10T01:00:00Z",
"2012-12-10T02:00:00Z",
"2012-12-10T03:00:00Z",
"2012-12-10T04:00:00Z",
"2012-12-10T05:00:00Z",
"2012-12-10T06:00:00Z",
"2012-12-10T07:00:00Z",
"2012-12-10T08:00:00Z",
"2012-12-10T09:00:00Z",
"2012-12-10T10:00:00Z",
"2012-12-10T11:00:00Z",
"2012-12-10T12:00:00Z",
"2012-12-10T13:00:00Z"
]
}
}
}
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. For the UK observations web service this is set to obs
- 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 time-steps 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 time-step, expressed according to the ISO 8601 combined date and time convention.
UK observations data feed
Accessing the feed via its web service
Description of web service
This provides access to the hourly weather observations made over the 24 hour period preceding the time at which the web service was last updated. The data provided by the web service is updated on an hourly basis, and at any given point in time the exact set of time-steps that are available can be obtained using the capabilities web service. For a full list of the sites, call the UK observations site list data feed [HL].
Possible use cases for this web service with example URLs
Since this web service supplies observation data, whenever this web service is used the resource category field in the URL should be set to wxobs, the temporal resolution should be set to hourly, 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 observations for a specified location at each available time-step. In this case you specify the location ID explicitly in the location field.
Example: to obtain observations for a specified location at all available times in XML format:
http://datapoint.metoffice.gov.uk/public/data/val/wxobs/all/xml/[LocationID]?res=hourly&key=<API key>
The above example would return 24 observation time-steps in XML format, resulting in a file size of approximately 2.4 kB
2. You would like a complete list of the observations 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 observations for every location in the UK at a particular time in XML format:
http://datapoint.metoffice.gov.uk/public/data/val/wxobs/all/xml/all?res=hourly&time=2011-11-10T18Z&key=<API key>
The above example would return around 100 observation time-steps in XML format, resulting in a file size of approximately 43 kB
3. You would like a complete list of the observations for every location in the UK at each available time-step. 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 observations for every location in the UK at all available times in XML format:
http://datapoint.metoffice.gov.uk/public/data/val/wxobs/all/xml/all?res=hourly&key=<API key>
The above example would return around 2,400 observation time-steps in XML format, resulting in a file size of approximately 250 kB
Example of XML and JSON responses
The following examples show a typical result of a call to the UK observations web service requesting a complete list of the observations for Heathrow at each available time-step. 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/wxobs/all/xml/3772?res=hourly&key=<APIkey>
<?xml version="1.0" encoding="UTF-8"?>
<SiteRep>
<Wx>
<Param name="G" units="mph">Wind Gust</Param>
<Param name="T" units="C">Temperature</Param>
<Param name="V" units="m">Visibility</Param>
<Param name="D" units="compass">Wind Direction</Param>
<Param name="S" units="mph">Wind Speed</Param>
<Param name="W" units="">Weather Type</Param>
<Param name="P" units="hpa">Pressure</Param>
<Param name="Pt" units="Pa/s">Pressure Tendency</Param>
<Param name="Dp" units="C">Dew Point</Param>
<Param name="H" units="%">Screen Relative Humidity</Param>
</Wx>
<DV dataDate="2013-11-26T14:00:00Z" type="Obs">
<Location i="3772" lat="51.479" lon="-0.449" name="HEATHROW"
country="ENGLAND" continent="EUROPE" elevation="25.0">
<Period type="Day" value="2013-11-25Z">
<Rep D="N" H="71.0" P="1037" S="7" T="7.2" V="23000" W="7" Pt="F"
Dp="2.2">840</Rep>
<Rep D="NNW" H="70.0" P="1037" S="7" T="7.0" V="21000" W="8" Pt="F"
Dp="1.9">900</Rep>
<Rep D="N" H="72.0" P="1038" S="8" T="6.6" V="26000" W="8" Pt="F"
Dp="2.0">960</Rep>
<Rep D="N" H="75.0" P="1038" S="6" T="6.4" V="22000" W="8" Pt="R"
Dp="2.3">1020</Rep>
<Rep D="N" H="74.0" P="1038" S="7" T="6.3" V="23000" W="8" Pt="R"
Dp="2.1">1080</Rep>
<Rep D="NNW" H="76.0" P="1039" S="6" T="6.2" V="23000" W="8" Pt="R"
Dp="2.2">1140</Rep>
<Rep D="N" H="76.0" P="1039" S="7" T="6.0" V="24000" W="8" Pt="R"
Dp="2.1">1200</Rep>
<Rep D="N" H="76.0" P="1039" S="6" T="5.8" V="21000" W="8" Pt="R"
Dp="1.9">1260</Rep>
<Rep D="N" H="75.0" P="1039" S="6" T="5.7" V="22000" W="8" Pt="R"
Dp="1.7">1320</Rep>
<Rep D="NNW" H="74.0" P="1039" S="5" T="5.5" V="25000" W="8" Pt="F"
Dp="1.2">1380</Rep>
</Period>
<Period type="Day" value="2013-11-26Z">
<Rep D="NNW" H="75.0" P="1039" S="6" T="5.3" V="23000" W="8" Pt="R"
Dp="1.2">0</Rep>
<Rep D="NNW" H="74.0" P="1040" S="6" T="5.3" V="23000" W="8" Pt="R"
Dp="1.1">60</Rep>
<Rep D="NNW" H="74.0" P="1039" S="5" T="5.2" V="24000" W="8" Pt="R"
Dp="0.9">120</Rep>
<Rep D="NNW" H="74.0" P="1039" S="5" T="4.9" V="26000" W="8" Pt="F"
Dp="0.7">180</Rep>
<Rep D="NNW" H="75.0" P="1039" S="6" T="4.3" V="24000" W="8" Pt="F"
Dp="0.3">240</Rep>
<Rep D="NNW" H="79.0" P="1039" S="5" T="2.9" V="22000" W="2" Pt="F"
Dp="-0.4">300</Rep>
<Rep D="WNW" H="85.0" P="1039" S="5" T="1.6" V="18000" W="0" Pt="S"
Dp="-0.6">360</Rep>
<Rep D="NW" H="87.0" P="1039" S="2" T="1.0" V="15000" W="0" Pt="R"
Dp="-0.9">420</Rep>
<Rep D="W" H="87.0" P="1040" S="3" T="0.9" V="15000" W="1" Pt="R"
Dp="-1.0">480</Rep>
<Rep D="W" H="82.0" P="1040" S="2" T="2.2" V="16000" W="1" Pt="R"
Dp="-0.5">540</Rep>
<Rep D="W" H="78.0" P="1040" S="2" T="3.5" V="16000" W="1" Pt="R"
Dp="0.0">600</Rep>
<Rep D="WNW" H="74.0" P="1040" S="3" T="4.8" V="13000" W="1" Pt="R"
Dp="0.5">660</Rep>
<Rep D="WNW" H="72.0" P="1039" S="6" T="5.8" V="13000" W="1" Pt="F"
Dp="1.1">720</Rep>
<Rep D="NNW" H="63.0" P="1039" S="5" T="7.4" V="23000" W="1" Pt="F"
Dp="0.9">780</Rep>
<Rep D="NNW" H="62.0" P="1038" S="6" T="7.4" V="30000" W="7" Pt="F"
Dp="0.5">840</Rep>
</Period>
</Location>
</DV>
</SiteRep>
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/wxobs/all/json/3772?res=hourly&key=<APIkey>
{
�SiteRep":{
�Wx":{
�Param":[{
�name":"G","units":"mph","$":"Wind Gust"
},
{
�name":"T","units":"C","$":"Temperature"
},
{
�name":"V","units":"m","$":"Visibility"
},
{
�name":"D","units":"compass","$":"Wind Direction"
},
{
�name":"S","units":"mph","$":"Wind Speed"
},
{
�name":"W","units":"","$":"Weather Type"
},
{
�name":"P","units":"hpa","$":"Pressure"
},
{
�name":"Pt","units":"Pa/s","$":"Pressure Tendency"
},
{
�name":"Dp","units":"C","$":"Dew Point"
},
{
�name":"H","units":"%","$":"Screen Relative Humidity�
}
]
},"DV":{
�dataDate":"2013-11-26T13:00:00Z","type":"Obs",
"Location":{
�i":"3772","lat":"51.479","lon":"-0.449","name":"HEATHROW","country":"ENGLAND","continent":"EUROPE","elevation":"25.0","Period":[{
�type":"Day","value":"2013-11-25Z","Rep":[{
�D":"N","H":"71.0","P":"1037","S":"7","T":"7.2","V":"23000","W":"7","Pt":"F","Dp":"2.2","$":"840"
},
{
�D":"NNW","H":"70.0","P":"1037","S":"7","T":"7.0","V":"21000","W":"8","Pt":"F","Dp":"1.9","$":"900"
},
{
�D":"N","H":"72.0","P":"1038","S":"8","T":"6.6","V":"26000","W":"8","Pt":"F","Dp":"2.0","$":"960"
},
{
�D":"N","H":"75.0","P":"1038","S":"6","T":"6.4","V":"22000","W":"8","Pt":"R","Dp":"2.3","$":"1020"
},
{
�D":"N","H":"74.0","P":"1038","S":"7","T":"6.3","V":"23000","W":"8","Pt":"R","Dp":"2.1","$":"1080"
},
{
�D":"NNW","H":"76.0","P":"1039","S":"6","T":"6.2","V":"23000","W":"8","Pt":"R","Dp":"2.2","$":"1140"
},
{
�D":"N","H":"76.0","P":"1039","S":"7","T":"6.0","V":"24000","W":"8","Pt":"R","Dp":"2.1","$":"1200"
},
{
�D":"N","H":"76.0","P":"1039","S":"6","T":"5.8","V":"21000","W":"8","Pt":"R","Dp":"1.9","$":"1260"
},
{
�D":"N","H":"75.0","P":"1039","S":"6","T":"5.7","V":"22000","W":"8","Pt":"R","Dp":"1.7","$":"1320"
},
{
�D":"NNW","H":"74.0","P":"1039","S":"5","T":"5.5","V":"25000","W":"8","Pt":"F","Dp":"1.2","$":"1380�
}
]
},
{
�type":"Day","value":"2013-11-26Z","Rep":[{
�D":"NNW","H":"75.0","P":"1039","S":"6","T":"5.3","V":"23000","W":"8","Pt":"R","Dp":"1.2","$":"0"
},
{
�D":"NNW","H":"74.0","P":"1040","S":"6","T":"5.3","V":"23000","W":"8","Pt":"R","Dp":"1.1","$":"60"
},
{
�D":"NNW","H":"74.0","P":"1039","S":"5","T":"5.2","V":"24000","W":"8","Pt":"R","Dp":"0.9","$":"120"
},
{
�D":"NNW","H":"74.0","P":"1039","S":"5","T":"4.9","V":"26000","W":"8","Pt":"F","Dp":"0.7","$":"180"
},
{
�D":"NNW","H":"75.0","P":"1039","S":"6","T":"4.3","V":"24000","W":"8","Pt":"F","Dp":"0.3","$":"240"
},
{
�D":"NNW","H":"79.0","P":"1039","S":"5","T":"2.9","V":"22000","W":"2","Pt":"F","Dp":"-0.4","$":"300"
},
{
�D":"WNW","H":"85.0","P":"1039","S":"5","T":"1.6","V":"18000","W":"0","Pt":"S","Dp":"-0.6","$":"360"
},
{
�D":"NW","H":"87.0","P":"1039","S":"2","T":"1.0","V":"15000","W":"0","Pt":"R","Dp":"-0.9","$":"420"
},
{
�D":"W","H":"87.0","P":"1040","S":"3","T":"0.9","V":"15000","W":"1","Pt":"R","Dp":"-1.0","$":"480"
},
{
�D":"W","H":"82.0","P":"1040","S":"2","T":"2.2","V":"16000","W":"1","Pt":"R","Dp":"-0.5","$":"540"
},
{
�D":"W","H":"78.0","P":"1040","S":"2","T":"3.5","V":"16000","W":"1","Pt":"R","Dp":"0.0","$":"600"
},
{
�D":"WNW","H":"74.0","P":"1040","S":"3","T":"4.8","V":"13000","W":"1","Pt":"R","Dp":"0.5","$":"660"
},
{
�D":"WNW","H":"72.0","P":"1039","S":"6","T":"5.8","V":"13000","W":"1","Pt":"F","Dp":"1.1","$":"720"
},
{
�D":"NNW","H":"63.0","P":"1039","S":"5","T":"7.4","V":"23000","W":"1","Pt":"F","Dp":"0.9","$":"780�
}
]
}
]
}
}
}
}
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 Param objects, defined below.
Param
A Param object contains the definition of one of the attributes in a single observation (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 Obs
- dataDate: This describes the date and time at which the observation 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
- elevation: This provides the elevation 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 observation, and contains the elements listed in the table below. The units for each of these elements are described in Unit definitions.
- W: This gives the Weather Type
- V: This gives the Visibility
- T: This gives the Temperature
- S: This gives the Wind Speed
- P: This gives the Pressure
- G: This gives the Wind Gust
- D: This gives the Wind Direction
- Pt: This gives the pressure tendency
- Dp: This gives the Dew Point
- H: This gives the Screen Relative Humidity
The value of a Rep object ($ in the JSON representation) denotes the number of minutes after midnight UTC on the day represented by the Period object in which the Rep object is found.