Atmosphere API

All things Atmosphere

If you think about all the different types of data about our environment, you can divide them into two main groups: the largely static and the ever changing. Static data would be things such as soil type or its position on earth. The ever changing, or dynamic data, would be all things pertaining to the weather. The Atmosphere API deals with all dynamic environmental data. You’ll find everything from temperature and humidity to wind speed and solar radiation. Since the data is ever changing, you query it with a location and time. You can query it for current (or most recent) data, as well as historical or forecast data. And there are two time aggregations available out of the box: hourly and daily. Let’s look at each one.

How to get hourly data

To get hourly data you make an HTTP call to https://developer-api.etwater.com/atmosphere/hourly along with your access token in the request headers.

cURL request example

Here is how you’d make the call using cURL:

curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/atmosphere/hourly'

Response example

And here is what you’d get back from the Unity API:

{
	"status": 1
}

Note the status field in the response. It will be included with every Atmosphere API response. It indicates the state your query is in. Status values could be the following:

Status Description
0 Everything is completed. This status is passed along with data requested.
1 Query is in progress. Data is being gathered or prepared.
2 Query is unproccessable. Data is not available for a given location or within a given timeframe.

 

Whenever you get status equal to 1 you can repeat you request in one or more seconds until the status changes.

Once the data is ready your response will look something like this:

Response example with data

{
	"status": 0,
	"hourly": [
		{
			"dewPointC": 11.87,
			"relativeHumidityPercent": 90,
			"pressureKilopascals": 101.456,
			"temperatureC": 12.7,
			"cloudCoverPercent": 37,
			"windKmH": 11.088,
			"precipitationProbabilityPercent": 0,
			"ghWm2": 0,
			"rainMm": 0,
			"time": 1475132400,
			"etMm": 0.0037170602724583
		},
====================== REDUCED ====================
		{
			"dewPointC": 11.04,
			"relativeHumidityPercent": 87,
			"pressureKilopascals": 101.871,
			"temperatureC": 12.95,
			"cloudCoverPercent": 46,
			"windKmH": 13.5,
			"precipitationProbabilityPercent": 0,
			"ghWm2": 0,
			"rainMm": 0,
			"time": 1475215200,
			"etMm": 0.015646605460157
		}
	]
}

(Since the response was for a whole day of hourly data it returned a lot of data. For brevity the above example response was trimmed. The removed data was replaced with REDUCED in the above code block.)

POSTMAN request and response example

If you’re using Postman, here is what that would look like:

Now, you probably noticed that we did not query the Atmosphere API with a location or time. Since we didn’t, by default it used our current location based on the IP the call was made from, and as we didn’t provide a time either, it assumed we want only current (or most recent) data.

Of course all of those parameters could be added to the request if needed. For example, let’s query for data with the following coordinates:

latitude = 37.762026
longitude = -122.434533

And let’s get data for September 28, 2016. Since we want hourly data for the whole day, we need to provide a start and an end time to define our  timeframe. Each one should be a Unix timestamp (more about unix time: https://en.wikipedia.org/wiki/Unix_time). The Unity API is also capable of providing forecast data. To get a forecast, simply provide a startTimestamp and endTimestamp in the future.

cURL request example

curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/atmosphere/hourly?latitude=37.762026&longitude=-122.434533&startTimestamp=1475010000&endTimestamp=1475096400'

Response example for a specific location and time

{
	"status": 0,
	"hourly": [
		{
			"dewPointC": 10.63,
			"relativeHumidityPercent": 49,
			"pressureKilopascals": 101.109,
			"temperatureC": 22.24,
			"cloudCoverPercent": 23,
			"windKmH": 9.072,
			"precipitationProbabilityPercent": 0,
			"ghWm2": 653,
			"rainMm": 0,
			"time": 1475010000,
			"etMm": 0.51054294908213
		},
====================== REDUCED ====================
		{
			"dewPointC": 11.58,
			"relativeHumidityPercent": 76,
			"pressureKilopascals": 101.185,
			"temperatureC": 15.97,
			"cloudCoverPercent": 32,
			"windKmH": 11.736,
			"precipitationProbabilityPercent": 0,
			"ghWm2": 244,
			"rainMm": 0,
			"time": 1475096400,
			"etMm": 0.18957552584245
		}
	]
}

(The above response example was reduced for brevity. Your real response would have all the blocks of data for each our.)

POSTMAN request and response example

If you’re using Postman, here is what that would look like:

How to get daily data

Request for daily aggregated data is similar to hourly data requests, except you call a slightly different url: https://developer-api.etwater.com/atmosphere/daily.

cURL request example

curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/atmosphere/daily?latitude=37.762026&longitude=-122.434533'

Response example

{
	"status": 0,
	"daily": [
		{
			"dewPointC": 11.87,
			"minWindKmH": 8.244,
			"maxWindKmH": 17.784,
			"avgRelativeHumidityPercent": 83.833333333333,
			"maxPrecipitationProbabilityPercent": 0,
			"maxTemperatureC": 20.69,
			"minTemperatureC": 12.46,
			"avgCloudCoverPercent": 48.083333333333,
			"ghWm2": 1498,
			"rainMm": 0,
			"sunset": 0,
			"time": 1475107200,
			"etMm": 2.030759115295,
			"sunrise": 1475200613,
			"avgPressureKilopascals": 0
		}
	]
}

POSTMAN request and response example

And if you’re using Postman, here is what that would look like:

How to get only the data you want

It’s possible (and recommended) to reduce the number of data fields you’re receiving in the API response by adding a keys parameter to your query.

KeyDescription
ETEvapotranspiration
RAINRain (reported in millimeters (mm))
SOLAR_IRRADIATIONGlobal Horizontal Irradiance (reported in W/m2)
TEMPERATURETemperature (reported in degrees Celsius)
DEWPOINTDewpoint (reported in degrees Celsius)
WINDWind speed (reported in kilometers per hour (km/h))
RELATIVE_HUMIDITYRelative humidity (reported as a percentage)
PRECIPITATION_PROBABILITYChance of rain (reported as a percentage)
CLOUD_COVERCloud coverage (reported as a percentage)
PRESSUREAir pressure (reported as kilo Pascal (kPa))
SUNRISESunrise (reported as a Unix timestamp)
SUNSETSunset (reported as a Unix timestamp)

 

For example, let’s query for a week of daily data, including only ET, Horizontal Irradiance and Rain:

cURL request example

curl -H'Authorization: Bearer $ACCESS_TOKEN' 'https://developer-api.etwater.com/api/v1/atmosphere/daily?longitude=-122.434533&latitude=37.762026&startTimestamp=1474502400&endTimestamp=1475020800&keys=ET,SOLAR_IRRADIATION,RAIN'

Response example

{
	"status": 0,
	"daily": [
		{
			"ghWm2": 2026,
			"rainMm": 0,
			"etMm": 1.6280571646719,
			"time": 1475020800
		},
		{
			"ghWm2": 5126,
			"rainMm": 0,
			"etMm": 4.6875087537283,
			"time": 1474934400
		},
		{
			"ghWm2": 5472,
			"rainMm": 0,
			"etMm": 5.1977538927658,
			"time": 1474848000
		},
		{
			"ghWm2": 5466,
			"rainMm": 0,
			"etMm": 4.8620765592805,
			"time": 1474761600
		},
		{
			"ghWm2": 5547,
			"rainMm": 0,
			"etMm": 3.9377239210857,
			"time": 1474675200
		},
		{
			"ghWm2": 5581,
			"rainMm": 0,
			"etMm": 3.6957859902198,
			"time": 1474588800
		},
		{
			"ghWm2": 5727,
			"rainMm": 0,
			"etMm": 3.6873513958984,
			"time": 1474502400
		}
	]
}

As you can see, we get back only what we requested—a leaner, cleaner and faster response.

POSTMAN request and response example

Here is the same using Postman: