CoCoRaHS Web services tutorial



Station Metadata Export Examples

Here is a request for all stations in Minnesota as a CSV file:
http://data.cocorahs.org/cocorahs/export/exportstations.aspx?format=csv&state=mn

Add "&stationstatus=reporting" to get only the reporting stations or "&stationstatus=closed" for closed stations:
http://data.cocorahs.org/cocorahs/export/exportstations.aspx?format=csv&state=mn&stationstatus=reporting
http://data.cocorahs.org/cocorahs/export/exportstations.aspx?format=csv&state=mn&stationstatus=closed

Add "&TimesInGMT=True" if you need GMT formatting. Here is an example that does that, and filters on Anoka county in XML format:
http://data.cocorahs.org/cocorahs/export/exportstations.aspx?format=xml&state=mn&county=aa&TimesInGMT=True

Please note that if you set TimesInGMT to true, the datetime value passed in via the URL will be assumed to be in GMT.

There is also the ability to filter on the station CreationDate or TimeStamp, by individual day or date range.
- The stationdatetype=[ timestamp | creationdate ] determines which field to filter on.
- If the "date" variable is used with stationdatetype=creationdate the stations will be filtered by creationdate=request date.
- If the "date" variable is used with stationdatetype=timestamp the stations will be filtered by timestamp >=request date. This is available for applications that poll the export to sync the cocorahs export with an internally managed station list. This provides a way to get only stations that have been added or modified since the last sync time.

- You can also use "startdate" and "enddate" to define a date range to filter on either the creationdate or timestamp fields.

- The date formatting is flexible, but I prefer if you use the following format to be in compliance with future date formatting requirements I will be adding.
[yyyy'-'MM'-'dd'T'HH':'mm':'ss] the "T" separator for time can be replaced with a space, and the seconds are optional.

Here is an example of all stations added in May 2010:
http://data.cocorahs.org/cocorahs/export/exportstations.aspx?format=xml&state=mn&stationdatetype=creationdate&startdate=2010-05-01&enddate=2010-05-31

Here is an example with the station(s) that have been added or modified since October 17, 2010 at 1PM :
http://data.cocorahs.org/cocorahs/export/exportstations.aspx?format=xml&state=mn&stationdatetype=timestamp&date=2010-10-17T13:00

Lastly, if you can use the dtf variable to control the date time format in the result set.
Here are the values with options:
1 = yyyy-MM-dd hh:mm tt
2 = HH:mm 'UT' MMM dd yyyy
3 = yyyy-MM-dd HH:mm:ss

Here is the previous example with the 3rd formatting option applied:
http://data.cocorahs.org/cocorahs/export/exportstations.aspx?format=xml&state=mn&stationdatetype=timestamp&date=2010-10-17T13:00&dtf=3


Data Export Examples

You can view some of the options from the export manager:
http://data.cocorahs.org/cocorahs/export/exportmanager.aspx

Here is an example export for Minnesota for July 4, 2010 as a XML file:
http://data.cocorahs.org/cocorahs/export/exportreports.aspx?ReportType=Daily&dtf=1&Format=XML&State=OK&ReportDateType=reportdate&Date=7/4/2010&TimesInGMT=False

You can replace Format=XML with Format=XMLCompact to change the report structure from having report fields in XML nodes to putting them in attributes. This helps if you are using the XML in a client-side javascript based system. I set it up for a Google maps proto-type, but our upgraded mapping system will use JSON because it is faster than either parsing either xml format.

This request can be simplified to:
http://data.cocorahs.org/cocorahs/export/exportreports.aspx?Format=CSV&State=MN&Date=7/4/2010

Here is an example link for the daily reports for Minnesota as a CSV file:
http://data.cocorahs.org/cocorahs/export/exportreports.aspx?ReportType=Daily&dtf=1&Format=XML&State=mn&ReportDateType=reportdate&Date=7/4/2010&TimesInGMT=False

This simplified link will provide the same data set with the defaults set. For instance if ReportDate is not included, it is set to today's date:
http://data.cocorahs.org/cocorahs/export/exportreports.aspx?Format=XML&State=MN

The daily reports include snow data. We do not yet include hail data in the export, but it is on my to-do list. We do offer multi-day reports, just change the ReportType value from Daily to MultiDay in the request.

You can request a date range by removing the Date variable and replacing it with StartDate and EndDate variables. Here is an example with two days of data for Minnesota:
http://data.cocorahs.org/cocorahs/export/exportreports.aspx?ReportType=MultiDay&dtf=1&Format=XML&State=MN&ReportDateType=reportdate&StartDate=7/29/2010&EndDate=7/30/2010&TimesInGMT=False

On the exportmanager.aspx page, you will see a radio button for Report Date Type, this corresponds to the ReportDateType URL variable whose values are reportdate and timestamp. The default is reportdate, which provides the reports with an observation date that matches the Date variable value passed in. If you use timestamp, you will get all reports that have been added or edited since the datetime value passed in the Date variable. This is for automated scenarios where you want to keep your data set synced but don't want to get back thousands of reports you already have, just the few that have been added or edited. Here is an example of that URL:
http://data.cocorahs.org/cocorahs/export/exportreports.aspx?ReportType=Daily&dtf=1&Format=XML&State=MN&ReportDateType=timestamp&Date=3/2/2011%207:00%20AM&TimesInGMT=False