CST API

Authentication

All requests to the Certified Snowfall Totals API require authentication via HTTP Basic Auth. To authenticate you send the provided API key as the basic auth username and leave the password blank.

For example, given the api key api_key_test_abc123 a request would look like:

curl https://certifiedsnowfalltotals.com/api/test -u api_key_test_abc123:

Responses

Responses will have an HTTP response code designating the status of your request and a JSON formatted body with the results of the request. Generally a 2xx response indicates a success, a 4xx response indicates an error caused by query parameters and a 5xx response indicates an error with Weather Works' servers.

Examples

Reference

Test

For testing

curl https://certifiedsnowfalltotals.com/api/test -u api_key_test_abc123:
true

Locations

Get location

Get information about a single location attached to your account.

Params:

  • location_id
curl https://certifiedsnowfalltotals.com/api/locations/58429 -u api_key_test_abc123:
{
	"id": 58429,
	"city": "Hackettstown",
	"state": "NJ",
	"zipcode": "07840",
	"county": "Warren",
	"premium": false,
	"latitude": 40.8564,
	"longitude": -74.8237
}

List locations

Retrieve a list of all locations attached to your account

curl https://certifiedsnowfalltotals.com/api/locations -u api_key_test_abc123:
[
	{
		"id": 19456,
		"city": "Chicago",
		"state": "IL",
		"zipcode": "60602",
		"county": "Cook",
		"premium": false,
		"latitude": 41.8832,
		"longitude": -87.6311
	},
	{
		"id": 19458,
		"city": "Chicago",
		"state": "IL",
		"zipcode": "60604",
		"county": "Cook",
		"premium": false,
		"latitude": 41.8794,
		"longitude": -87.6288
	},
	...
]

Storms

Get storm

Retrieve data from a single storm

Params:

  • storm_id
curl https://certifiedsnowfalltotals.com/api/storms/58429 -u api_key_test_abc123:
{
	"id": 16709,
	"start": 1423425600,
	"end": 1423558800,
	"storm_locations": [
		{
			"location": {
				"id": "57585",
				"city": "Independence",
				"state": "NJ",
				"zipcode": "07840"
			},
			"data": {
				"start" : "2/8/2015 4:00:00 PM",
				"end": "2/10/2015 4:00:00 AM",
				"precip_type": "Wintry Mix",
				"total": "1.1",
				"total_accumulation": 1.1,
				"total_trace": null,
				"ice": "Coating",
				"ice_accretion": 0,
				"ice_trace": "Coating",
				"note": "",
				"narrative": "<span style=\"font-weight:bold;\">Long Duration Wintry Mix</span><br/><br/>Mixed showers of snow, sleet and freezing rain developed between 1 and 3 AM on February 9th with temperatures in the mid to upper 20s. Combinations of sleet, freezing rain remained through the morning, briefly steady at times, with sleet accumulation and icing occurring. Any wintry mix lulled at times during the afternoon and evening, even giving way to periods of freezing mist as temperatures remained in the 20s. After 5-7pm, any light and intermittent mixed areas turned more widespread,and trended towards snow. This was steady at times as it continued into part of the overnight, before finally any ending by 1-4am on February 10th with temperatures remaining in the lower 20s.&nbsp;	<br/>"
			}
		},
		{
			"location": {
				"id": "58056",
				"city": "Bridgewater",
				"state": "NJ",
				"zipcode": "08807"
			},
			"data": {
				"start" : "2/8/2015 3:00:00 PM",
				"end": "2/10/2015 3:00:00 AM",
				"precip_type": "Wintry Mix",
				"total": "0.2",
				"total_accumulation": 0.2,
				"total_trace": null,
				"ice": "Coating",
				"ice_accretion": 0,
				"ice_trace": "Coating",
				"note": "",
				"narrative": "<span style=\"font-weight:bold;\">Long Duration Wintry Mix</span><br/><br/>Mixed showers of snow, sleet and freezing rain developed between 1 and 3 AM on February 9th with temperatures in the mid to upper 20s. Combinations of sleet, freezing rain remained through the morning, briefly steady at times, with sleet accumulation and icing occurring. Any wintry mix lulled at times during the afternoon and evening, even giving way to periods of freezing mist as temperatures remained in the 20s. After 5-7pm, any light and intermittent mixed areas turned more widespread,and trended towards snow. This was steady at times as it continued into part of the overnight, before finally any ending by 1-4am on February 10th with temperatures remaining in the lower 20s.&nbsp;	<br/>"
			}
		},
		...
	]
}

List storms

Retrieves storms that have been published queried either by when the storm occured or the date when it was published. Queries should be constructed to limit the amount of results; if too much data is requested the endpoint will fail and an http error status code will be returned. Some amount of time restriction must be present in the query and can be achieved one of two ways:

  1. Pass a publish_start
  2. Pass a from as well as a to

Query string params:

  • from (optional)

    Datetime string in local timezone (ex: 2014-02-14 04:00:00)

    Used along with to in order to filter down to storms that intersect the queried range

    The datetime string should be URL encoded

  • to (optional)

    Datetime string in local timezone (ex: 2014-02-14 04:00:00)

    Used along with from in order to filter down to storms that intersect the queried range

    The datetime string should be URL encoded

  • zipcode (optional)

    String (ex: 07840)

    Filters down to only locations that match the zipcode

  • locations (optional)

    Comma-seperated list of location ids

  • publish_start (optional)

    Unix timestamp (ex: 1440043200)

    Filters down to storms published between publish_start and publish_end

  • publish_end (optional)

    Unix timestamp (ex: 1440129600)

    Filters down to storms published between publish_start and publish_end

  • old_format (optional)

    Boolean (true or false)

    Default: false

  • narrative_as_html (optional)

    Boolean (true or false)

    Default: true

    Whether to return the narrative containing html or split into component pieces (title, body, footer)

curl 'https://certifiedsnowfalltotals.com/api/storms?from=2015-03-31+00:00:00&to=2015-03-31+23:59:59' -u api_key_test_abc123:
[
	{
		"id": "17490",
		"start": "3/31/2015 12:00:00 PM",
		"end": "3/31/2015 9:00:00 PM",
		"storm_locations": [
			{
				"location": {
					"id": "57585",
					"city": "Independence",
					"state": "NJ",
					"zipcode": "07840"
				},
				"data": {
					"start" : "3/31/2015 12:00:00 PM",
					"end": "3/31/2015 8:00:00 PM",
					"precip_type": "Snow",
					"total": "1.5",
					"total_accumulation": 1.5,
					"total_trace": null,
					"ice": "N/A",
					"ice_accretion": 0,
					"ice_trace": null,
					"note": "Up to 2\" in elevations above 800 ft.",
					"narrative": "<span style=\"font-weight:bold;\">End of March Snow</span><br/><br/>Beginning 12-2pm on March 31st, areas of snow moved into the area from the west with temperatures ranging from 36-41 degrees. Snow fell steady to heavy at times into the afternoon and evening before ending by 6-8pm with temperatures 32-35 degrees, before falling into the 20s overnight.&nbsp; "
				}
			},
			{
				"location": {
					"id": "58056",
					"city": "Bridgewater",
					"state": "NJ",
					"zipcode": "08807"
				},
				"data": {
					"start" : "3/31/2015 1:00:00 PM",
					"end": "3/31/2015 9:00:00 PM",
					"precip_type": "Snow",
					"total": "Scattered Coating",
					"total_accumulation": 0.0,
					"total_trace": "Scattered Coating",
					"ice": "N/A",
					"ice_accretion": 0,
					"ice_trace": null,
					"note": "",
					"narrative": "<span style=\"font-weight:bold;\">Rain ending as snow</span><br/><br/>With temperatures in the low to mid 40s on March 31st, areas of rain showers moved into the area between 2-4pm. Temperatures fell into the mid 30s between 5-7pm as rain changed to snow, with a steady period of snow occurring before ending by 8-9pm.&nbsp;"
				}
			},
			...
		]
	},
	{
		"id": "17493",
		"start": "3/31/2015 1:00:00 PM",
		"end": "3/31/2015 10:00:00 PM",
		"storm_locations": [
			{
				"location": {
					"id": "63658",
					"city": "Mount Kisco",
					"state": "NY",
					"zipcode": "10549"
				},
				"data": {
					"precip_type": "Snow",
					"total": "0.2",
					"total_accumulation": 0.2,
					"total_trace": null,
					"ice": "N/A",
					"ice_accretion": 0,
					"ice_trace": null,
					"note": "",
					"narrative": "<span style=\"font-weight:bold;\">Another Snow Event to Close Out March</span><br/><br/>Combinations of rain and snow developed over the area between 1:30 and 3:30 PM. Many locations, particularly north of 287, changed to all snow for a while late in the afternoon into the early evening. Precipitation ended (mostly as snow) between 7 and 9 PM.&nbsp; &nbsp; At the onset of precipitation, the temperature was in the low 40s, but it quickly cooled into the mid and upper 30s. These mild temperatures during snowfall kept most of the accumulation on colder and grassy surfaces.<br/>"
				}
			}
		]
	}
]

List storms - old format

The old format is provided as an attempt to mimic the old SOAP service but in JSON.

curl https://certifiedsnowfalltotals.com/api/storms?publish_start=1427846400&old_format=true -u api_key_test_abc123:
[
	{
		"stormID": "17490",
		"locationID": "57585",
		"startTime": "3/31/2015 12:00:00 PM",
		"endTime": "3/31/2015 9:00:00 PM",
		"precipitationType": 1,
		"precipititationDescription": "Up to 2\" in elevations above 800 ft.",
		"total": "1.5",
		"zipCode": "07840",
		"city": "Independence",
		"state": "NJ",
		"narrative": "<span style=\"font-weight:bold;\">End of March Snow</span><br/><br/>Beginning 12-2pm on March 31st, areas of snow moved into the area from the west with temperatures ranging from 36-41 degrees. Snow fell steady to heavy at times into the afternoon and evening before ending by 6-8pm with temperatures 32-35 degrees, before falling into the 20s overnight.&nbsp; "
	},
	{
		"stormID": "17490",
		"locationID": "58056",
		"startTime": "3/31/2015 12:00:00 PM",
		"endTime": "3/31/2015 9:00:00 PM",
		"precipitationType": 1,
		"precipititationDescription": "Scattered Coating",
		"total": "0.0",
		"zipCode": "08807",
		"city": "Bridgewater",
		"state": "NJ",
		"narrative": "<span style=\"font-weight:bold;\">Rain ending as snow</span><br/><br/>With temperatures in the low to mid 40s on March 31st, areas of rain showers moved into the area between 2-4pm. Temperatures fell into the mid 30s between 5-7pm as rain changed to snow, with a steady period of snow occurring before ending by 8-9pm.&nbsp;"
	},
	{
		"stormID": "17493",
		"locationID": "63658",
		"startTime": "3/31/2015 1:00:00 PM",
		"endTime": "3/31/2015 10:00:00 PM",
		"precipitationType": 1,
		"precipititationDescription": "",
		"total": "0.2",
		"zipCode": "10549",
		"city": "Mount Kisco",
		"state": "NY",
		"narrative": "<span style=\"font-weight:bold;\">Another Snow Event to Close Out March</span><br/><br/>Combinations of rain and snow developed over the area between 1:30 and 3:30 PM. Many locations, particularly north of 287, changed to all snow for a while late in the afternoon into the early evening. Precipitation ended (mostly as snow) between 7 and 9 PM.&nbsp; &nbsp; At the onset of precipitation, the temperature was in the low 40s, but it quickly cooled into the mid and upper 30s. These mild temperatures during snowfall kept most of the accumulation on colder and grassy surfaces.<br/>"
	},
	...
]

Cumulatives

Retrieve seasonal cumulative totals by passing the season in the url. Data is available for the current and past 2 seasons.

Params:

  • season

    The season is the first year of the season (2007 for 2007-2008, 2014 for 2014-2015).

Query string params:

  • locations (optional)

    Locations is a comma seperated list of location_ids (ex: ?locations=57585,58056,63658)

curl https://certifiedsnowfalltotals.com/api/cumulatives/2014 -u api_key_test_abc123:
[
	{
		"location": {
			"id": 19456,
			"city": "Chicago",
			"zipcode": "60602",
			"state": "IL"
		},
		"seasonal": 37.4,
		"monthly": [
			{
				"year": 2014,
				"month": 10,
				"storms": 1,
				"total": 0
			},
			{
				"year": 2015,
				"month": 1,
				"storms": 9,
				"total": 24.2
			},
			{
				"year": 2015,
				"month": 2,
				"storms": 11,
				"total": 8.4
			},
			{
				"year": 2015,
				"month": 3,
				"storms": 4,
				"total": 4.8
			}
		]
	},
	{
		"location": {
			"id": 19458,
			"city": "Chicago",
			"zipcode": "60604",
			"state": "IL"
		},
		"seasonal": 37.4,
		"monthly": [
			{
				"year": 2014,
				"month": 10,
				"storms": 1,
				"total": 0
			},
			{
				"year": 2015,
				"month": 1,
				"storms": 9,
				"total": 24.2
			},
			{
				"year": 2015,
				"month": 2,
				"storms": 11,
				"total": 8.4
			},
			{
				"year": 2015,
				"month": 3,
				"storms": 4,
				"total": 4.8
			}
		]
	},
	...
]

Generate a Storm Location PDF Report

Create a PDF for a single storm location. Once generated, a link to the PDF will be sent to the callback_url.

Query string params:

  • storm_id

  • location_id

  • callback_url

    The URL that will receive the link to the PDF once its available.

curl https://certifiedsnowfalltotals.com/api/generate_storm_location_pdf?location_id=123&storm_id=456&callback_url=https://mysite.com/pdf-callback -u api_key_test_abc123:
Response from the above request: 
{
	"id": 123,
	"code": "A1B2C3",
	"msg": "Pdf generation added to queue"
}
POST request sent by our server to the passed callback_url: 
{
	"id": 123,
	"code": "A1B2C3",
	"msg": "https://certifiedsnowfalltotals.com/report_codes/download_report/A1B2C3"
}

Example Workflow

  1. Make a request to the generate_storm_location_pdf endpoint with the storm location and the callback url that you want to receive the download url
  2. Make sure either the callback url is unique to this request or store the id/code to be able to identify which PDF the callback handler is receiving
  3. Wait. Once the PDF has been generated an http request will be POSTed to the callback url with a link to download the PDF
  4. Now that you have the link to download the PDF you can either forward that along to the requester, or download the file and manage it yourself

# Request a PDF be generated
curl "https://certifiedsnowfalltotals.com/api/generate_storm_location_pdf?location_id=123&storm_id=456&callback_url=https://mysite.com/PDFcallback.php" -u api_key_test_abc123:
# Response received
{
	"id": 123,
	"code": "A1B2C3",
	"msg": "Pdf generation added to queue"
}

# ... A few seconds later, the callback url receives a POST request ...

# https://mysite.com/PDFcallback.php
<?php
$requestData = file_get_contents("php://input");
$requestJson = json_decode($requestData);
$pdfId = $requestJson->id;
$pdfCode = $requestJson->code;
$downloadUrl = $requestJson->url;

# Once you have the download URL you can use it to download the PDF, or you can forward the URL to whoever is requesting the PDF so they can download it.
# In order to link the request and callback together in case there are multiple you can either:
# 	send a unique callback url that would identify the target
# 	or use the id or code fields to link together a request and callback.