ETwater | Unity API: How to use the Atmosphere API

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 [html]https://developer-api.etwater.com/atmosphere/hourly[/html] along with your access token in the request headers.

cURL request example

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

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

Response example

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

[json]{
	"status": 1
}
[/json]

Note the [html]status[/html] 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 [html]status[/html] equal to [html]1[/html] 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

[json]{
	"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
		}
	]
}
[/json]

(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 [html]REDUCED[/html] 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:

[json]latitude = 37.762026
longitude = -122.434533
[/json]

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 [html]startTimestamp[/html] and [html]endTimestamp[/html] in the future.

cURL request example

[json]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'
[/json]

Response example for a specific location and time

[json]{
	"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
		}
	]
}
[/json]

(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: [html]https://developer-api.etwater.com/atmosphere/daily[/html].

cURL request example

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

Response example

[json]{
	"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
		}
	]
}
[/json]

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 [html]keys[/html] parameter to your query.

Key	Description
ET	Evapotranspiration
RAIN	Rain (reported in millimeters (mm))
SOLAR_IRRADIATION	Global Horizontal Irradiance (reported in W/m²)
TEMPERATURE	Temperature (reported in degrees Celsius)
DEWPOINT	Dewpoint (reported in degrees Celsius)
WIND	Wind speed (reported in kilometers per hour (km/h))
RELATIVE_HUMIDITY	Relative humidity (reported as a percentage)
PRECIPITATION_PROBABILITY	Chance of rain (reported as a percentage)
CLOUD_COVER	Cloud coverage (reported as a percentage)
PRESSURE	Air pressure (reported as kilo Pascal (kPa))
SUNRISE	Sunrise (reported as a Unix timestamp)
SUNSET	Sunset (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

[json]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'
[/json]

Response example

[json]{
	"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
		}
	]
}
[/json]

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: