{ "openapi": "3.0.3", "info": { "title": "Ambient Weather REST API", "version": "1.0.0", "description": "Access an Ambient Weather user's weather station data programmatically using our REST API\n\n##### Authentication\n\nTwo API Keys are required for all REST API requests:\n\n+ `applicationKey` - identifies the developer / application. To create an application key please login to your AmbientWeather.net account page (https://ambientweather.net/account)\n\n+ `apiKey` - grants access to past/present data for a given user's devices. A typical consumer-facing application will initially ask the user to create an `apiKey` on their AmbientWeather.net account page (https://ambientweather.net/account) and paste it into the app. Developers for personal or in-house apps will also need to create an apiKey on their own account page.\n\n##### Rate Limiting\n\nAPI requests are capped at 1 request/second for each user's apiKey and 3 requests/second per applicationKey. When this limit is exceeded, the API will return a 429 response code. Please be kind to our servers :)\n\n##### Helper Libraries\n\n+ Node.js - https://github.com/owise1/ambient-weather-api\n\n+ PHP (Laravel) - https://github.com/Jafo232/ambient_api\n\n+ Rust - https://github.com/JoshuaKimsey/ambient-weather-api\n\n+ Go - https://github.com/lrosenman/ambient\n\n+ Python - https://github.com/avryhof/ambient_api\n\n+ Python (asyncio) - https://github.com/bachya/aioambient\n\n+ R - https://github.com/andrewflack/ambientweatheR\n\n+ Java - https://github.com/rsv-code/ambient-weather-java\n\n+ Swift - https://github.com/MikeManzo/SwiftyWeatherKit\n\n+ .NET 5 - https://github.com/ChaseDRedmon/Cirrus\n\n##### Other Resources\n\n+ API Wiki - https://github.com/ambient-weather/api-docs/wiki\n\n+ This documentation's repository - https://github.com/ambient-weather/api-docs" }, "servers": [ { "url": "https://rt.ambientweather.net/" } ], "paths": { "/v1/devices": { "get": { "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "macAddress": { "type": "string" }, "info": { "type": "object", "properties": { "name": { "type": "string" }, "location": { "type": "string" } } }, "lastData": { "type": "object", "properties": { "dateutc": { "type": "number" }, "date": { "type": "string", "format": "date-time" }, "winddir": { "type": "number" }, "windspeedmph": { "type": "number" }, "windgustmph": { "type": "number" }, "maxdailygust": { "type": "number" }, "windgustdir": { "type": "number" }, "winddir_avg2m": { "type": "number" }, "windspdmph_avg2m": { "type": "number" }, "winddir_avg10m": { "type": "number" }, "windspdmph_avg10m": { "type": "number" }, "tempf": { "type": "number" }, "humidity": { "type": "number" }, "baromrelin": { "type": "number" }, "baromabsin": { "type": "number" }, "tempinf": { "type": "number" }, "humidityin": { "type": "number" }, "hourlyrainin": { "type": "number" }, "dailyrainin": { "type": "number" }, "monthlyrainin": { "type": "number" }, "yearlyrainin": { "type": "number" }, "feelsLike": { "type": "number" }, "dewPoint": { "type": "number" } } } } } }, "example": [ { "macAddress": "00:00:00:00:00:00", "info": { "name": "My Weather Station", "location": "Home" }, "lastData": { "dateutc": 1515436500000, "date": "2018-01-08T18:35:00.000Z", "winddir": 58, "windspeedmph": 0.9, "windgustmph": 4, "maxdailygust": 5, "windgustdir": 61, "winddir_avg2m": 63, "windspdmph_avg2m": 0.9, "winddir_avg10m": 58, "windspdmph_avg10m": 0.9, "tempf": 66.9, "humidity": 30, "baromrelin": 30.05, "baromabsin": 28.71, "tempinf": 74.1, "humidityin": 30, "hourlyrainin": 0, "dailyrainin": 0, "monthlyrainin": 0, "yearlyrainin": 0, "feelsLike": 66.9, "dewPoint": 34.45380707462477 } } ] } } } }, "summary": "List User's Devices", "operationId": "list_users_devices", "description": "Provides a list of the user's available devices along with each device's most recent data.", "tags": [], "parameters": [ { "name": "applicationKey", "in": "query", "description": "Application Key", "required": true, "schema": { "type": "string" } }, { "name": "apiKey", "in": "query", "description": "API Key for user account", "required": true, "schema": { "type": "string" } } ] } }, "/v1/devices/{macAddress}": { "get": { "responses": { "429": { "$ref": "#/components/responses/RateLimited" }, "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "dateutc": { "type": "number" }, "date": { "type": "string", "format": "date-time" }, "winddir": { "type": "number" }, "windspeedmph": { "type": "number" }, "windgustmph": { "type": "number" }, "maxdailygust": { "type": "number" }, "windgustdir": { "type": "number" }, "winddir_avg2m": { "type": "number" }, "windspdmph_avg2m": { "type": "number" }, "winddir_avg10m": { "type": "number" }, "windspdmph_avg10m": { "type": "number" }, "tempf": { "type": "number" }, "humidity": { "type": "number" }, "baromrelin": { "type": "number" }, "baromabsin": { "type": "number" }, "tempinf": { "type": "number" }, "humidityin": { "type": "number" }, "hourlyrainin": { "type": "number" }, "dailyrainin": { "type": "number" }, "monthlyrainin": { "type": "number" }, "yearlyrainin": { "type": "number" }, "feelsLike": { "type": "number" }, "dewPoint": { "type": "number" } } } }, "example": [ { "dateutc": 1515436500000, "date": "2018-01-08T18:35:00.000Z", "winddir": 58, "windspeedmph": 0.9, "windgustmph": 4, "maxdailygust": 5, "windgustdir": 61, "winddir_avg2m": 63, "windspdmph_avg2m": 0.9, "winddir_avg10m": 58, "windspdmph_avg10m": 0.9, "tempf": 66.9, "humidity": 30, "baromrelin": 30.05, "baromabsin": 28.71, "tempinf": 74.1, "humidityin": 30, "hourlyrainin": 0, "dailyrainin": 0, "monthlyrainin": 0, "yearlyrainin": 0, "feelsLike": 66.9, "dewPoint": 34.45380707462477 } ] } } } }, "summary": "Query Device Data", "operationId": "query_device_data", "description": "Fetch data for a given device. Data is stored in 5 or 30 minute increments. A list of all possible fields is here: https://github.com/ambient-weather/api-docs/wiki/Device-Data-Specs", "tags": [], "parameters": [ { "name": "macAddress", "in": "path", "description": "device Mac Address", "required": true, "schema": { "type": "string" } }, { "name": "apiKey", "in": "query", "description": "API Key for user account", "required": true, "schema": { "type": "string" } }, { "name": "applicationKey", "in": "query", "description": "Application Key", "required": true, "schema": { "type": "string" } }, { "name": "endDate", "in": "query", "description": "The most recent datetime. Results descend from there. If left blank, the most recent results will be returned. Date format should be in milliseconds since the epoch or string representations outlined here: https://momentjs.com/docs/#/parsing/string/. Note: datetimes are stored in UTC.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "The maximum number of results to return (max: 288)", "schema": { "type": "number", "default": 288 } } ] } } }, "components": { "schemas": {}, "responses": { "RateLimited": { "description": "API requests are capped at 1 request/second for each user's apiKey and 3 requests/second per applicationKey. When this limit is exceeded, the API will return a 429 response code. Please be kind to our servers :)" } } }, "tags": [ { "name": "Ambient Realtime API", "description": "Access an Ambient Weather user's weather station data in realtime using our Realtime API\n\n##### Authentication\n\nYou will be working with two types of keys when using the Realtime API:\n\n+ `applicationKey` - identifies the developer / application. This key is passed to the server when you make the initial connection\n\n+ `apiKey` - identifies a user. This key grants read-only access to all of the devices for a given user. It is used in the `subscribe` command (see below)\n\n##### Websockets\n\nThe realtime API uses Websockets and is based on Socket.io (https://socket.io/). The easiest way to use the API is to use a Socket.io helper library. They are available in most languages.\n\nSocket.io Endpoint: `https://rt2.ambientweather.net/?api=1&applicationKey=....`\n\n* The realtime subdomain is different than the REST subdomain (realtime = `rt2`, REST = `rt`).\n\n* Include query parameters `api=1` to identify the api version\n\n* Include `applicationKey=....` to identify your application\n\nUpon successful connection, you'll send commands and listen for responses.\n\n##### Helper Libraries\n\n+ Node.js - https://github.com/owise1/ambient-weather-api\n\n###### Command: connect\n\nConnect to the Realtime API\n\n###### Command: disconnect\n\nDisconnect from the Realtime API\n\n###### Command: subscribe\n\nListen for new data from all the devices for users' apiKeys.\n\ncommand body - an object containing the property apiKeys that is an array of apiKeys:\n\n```\n{\n apiKeys:\n [\n 'multiple',\n 'apiKeys',\n 'are fine'\n ]\n}\n```\n\n###### Command: unsubscribe\n\nStop listening for new data from all the devices for users' apiKeys.\n\ncommand body - an object containing the property apiKeys that is an array of apiKeys:\n\n```\n{\n apiKeys:\n [\n 'multiple',\n 'apiKeys',\n 'are fine'\n ]\n}\n```\n\n##### Event: subscribed\n\n`subscribed` events are emitted after you send a `subscribe` or `unsubscribe` command. It will list all of the devices you are currently subscribed to and, if applicable, will return apiKeys that are not valid.\n\nevent body - an object containing one or more properties\n\n+ `devices` - an array containing objects for all of the devices you are currently subscribed to\n\n+ `invalidApiKeys` - an array of apiKeys that aren't valid\n\n```\n{\n \"devices\": [\n {\n \"macAddress\": \"00:00:00:00:00:00\",\n \"info\": {\n \"name\": \"My Weather Station\",\n \"location\": \"Home\"\n \"address\": \"this_device_physical_street_address\",\n \"elevation\": 60.72509002685547,\n \"coords\": {\n \"coords\": {\n \"lat\": xxx.xxxxxxx,\n \"lon\": xxx.xxxxxxx\n },\n \"geo\": {\n \"type\": \"Point\",\n \"coordinates\": [\n xxx.xxxxxxx,\n xxx.xxxxxxx\n ]\n }\n },\n \"lastData\": {\n \"dateutc\": 1515436500000,\n \"date\": \"2018-01-08T18:35:00.000Z\",\n \"winddir\": 58,\n \"windspeedmph\": 0.9,\n \"windgustmph\": 4,\n \"maxdailygust\": 5,\n \"windgustdir\": 61,\n \"winddir_avg2m\": 63,\n \"windspdmph_avg2m\": 0.9,\n \"winddir_avg10m\": 58,\n \"windspdmph_avg10m\": 0.9,\n \"tempf\": 66.9,\n \"humidity\": 30,\n \"baromrelin\": 30.05,\n \"baromabsin\": 28.71,\n \"tempinf\": 74.1,\n \"humidityin\": 30,\n \"hourlyrainin\": 0,\n \"dailyrainin\": 0,\n \"monthlyrainin\": 0,\n \"yearlyrainin\": 0,\n \"feelsLike\": 66.9,\n \"dewPoint\": 34.45380707462477\n \"deviceId\": \"this_devices_unique_device_id\"\n },\n \"apiKey\": \"the_apiKey_for_the_user_this_device_belongs_to\"\n }\n ],\n \"invalidApiKeys\": [\n 'an_api_key_that_is_not_any_good'\n ],\n \"method:\" \"subscribe\"\n}\n```\n\n##### Event: data\n\n`data` events are emitted when a device you are subscribed to sends new data. The data contains a `macAddress` property that you can use to match against the device list supplied by the `subscribed` event\n\nevent body - an object representing a device's data point\n\n```\n{\n \"macAddress\": \"00:00:00:00:00:00\",\n \"dateutc\": 1515436500000,\n \"date\": \"2018-01-08T18:35:00.000Z\",\n \"winddir\": 58,\n \"windspeedmph\": 0.9,\n \"windgustmph\": 4,\n \"maxdailygust\": 5,\n \"windgustdir\": 61,\n \"winddir_avg2m\": 63,\n \"windspdmph_avg2m\": 0.9,\n \"winddir_avg10m\": 58,\n \"windspdmph_avg10m\": 0.9,\n \"tempf\": 66.9,\n \"humidity\": 30,\n \"baromrelin\": 30.05,\n \"baromabsin\": 28.71,\n \"tempinf\": 74.1,\n \"humidityin\": 30,\n \"hourlyrainin\": 0,\n \"dailyrainin\": 0,\n \"monthlyrainin\": 0,\n \"yearlyrainin\": 0,\n \"feelsLike\": 66.9,\n \"dewPoint\": 34.45380707462477,\n \"tz\": \"America/New_York\"\n \"device\": {\n \"macAddress\": \"00:00:00:00:00:00\",\n \"info\": {\n \"name\": \"My Weather Station\",\n \"coords\": {\n \"coords\": {\n lat\": xxx.xxxxxxx,\n lon\": xxx.xxxxxxx\n },\n \"address\": \"his_device_physical_street_address\",\n \"location\": \"Home\",\n \"elevation\": 60.72509002685547,\n \"geo\": {\n \"type\": \"Point\",\n \"coordinates\": [\n xxx.xxxxxxx,\n xxx.xxxxxxx\n ]\n }\n },\n \"lastData\": {\n \"dateutc\": 1515436500000,\n \"date\": \"2018-01-08T18:35:00.000Z\",\n \"winddir\": 58,\n \"windspeedmph\": 0.9,\n \"windgustmph\": 4,\n \"maxdailygust\": 5,\n \"windgustdir\": 61,\n \"winddir_avg2m\": 63,\n \"windspdmph_avg2m\": 0.9,\n \"winddir_avg10m\": 58,\n \"windspdmph_avg10m\": 0.9,\n \"tempf\": 66.9,\n \"humidity\": 30,\n \"baromrelin\": 30.05,\n \"baromabsin\": 28.71,\n \"tempinf\": 74.1,\n \"humidityin\": 30,\n \"hourlyrainin\": 0,\n \"dailyrainin\": 0,\n \"monthlyrainin\": 0,\n \"yearlyrainin\": 0,\n \"feelsLike\": 66.9,\n \"dewPoint\": 34.45380707462477,\n \"deviceId\": \"this_devices_unique_device_id\",\n \"tz\": \"America/New_York\"\n },\n \"apiKey\": \"the_apiKey_for_the_user_this_device_belongs_to\"\n }\n}\n```" } ] }