{"swagger":"2.0","info":{"version":"v1","title":"AirGradient Sensor API"},"securityDefinitions":{"TokenQuery":{"type":"apiKey","name":"token","in":"query","description":"Access token for a place. You can obtain it from the Place settings page at https://app.airgradient.com/settings/place"}},"security":[{"TokenQuery":[]}],"paths":{"/public/api/v1/ping":{"get":{"summary":"Pings the server","operationId":"ping","parameters":[],"responses":{"200":{"description":"OK"}}}},"/public/api/v1/world/locations/measures/current":{"get":{"summary":"Gets the current measures of all locations that are made public to the world","operationId":"getCurrentMeasuresOfWorld","security":[],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Measures"}},"401":{"description":"Not authorized"},"404":{"description":"No data available"}}}},"/public/api/v1/world/locations/{locationId}/measures/current":{"get":{"summary":"Gets the current measures of a certain location that is made public to the world","operationId":"getCurrentMeasuresOfPublicLocation","security":[],"parameters":[{"name":"locationId","in":"path","description":"The unique id of the location","required":true,"type":"number"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Measure"}},"401":{"description":"Not authorized"},"404":{"description":"No data available"}}}},"/public/api/v1/locations/{locationId}/measures/current":{"get":{"summary":"Gets the current measures of a location","operationId":"getCurrentMeasures","parameters":[{"name":"locationId","in":"path","description":"The unique id of the location","required":true,"type":"number"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/GoMeasure"}},"401":{"description":"Not authorized"},"404":{"description":"No data available"}}}},"/public/api/v1/locations/measures/current":{"get":{"summary":"Gets all current measures of the place","operationId":"getAllCurrentMeasures","parameters":[],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Measures"}},"401":{"description":"Not authorized"},"404":{"description":"No data available"}}}},"/public/api/v1/alarms/triggered":{"get":{"summary":"Gets all currently triggered alarms of the place","operationId":"getTriggeredAlarms","parameters":[],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/TriggeredAlarms"}},"401":{"description":"Not authorized"},"404":{"description":"No data available"}}}},"/public/api/v1/locations/{locationId}/measures/raw":{"get":{"summary":"Gets the 200 most recent raw measures of a location or from a certain date range. The records are ordered by date descending","operationId":"getRawMeasures","parameters":[{"name":"locationId","in":"path","description":"The unique id of the location","required":true,"type":"number"},{"name":"from","in":"query","description":"The date from which measures are requested in ISO 8601 format with UTC offset (basic format, e.g 20240328T120500Z)","required":false,"type":"string"},{"name":"to","in":"query","description":"The date to which measures are requested in ISO 8601 format with UTC offset (basic format, e.g 20240328T230500Z). Must be after parameter from. The from .. to interval is limited to 2 days.","required":false,"type":"string"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/GoMeasures"}},"400":{"description":"Bad request"},"401":{"description":"Not authorized"},"404":{"description":"No data available"}}}},"/public/api/v1/locations/{locationId}/measures/past":{"get":{"summary":"Gets past measures of a location in 5 minute buckets or 60 minutes buckets (depending on what is available)","operationId":"getPastMeasures","parameters":[{"name":"locationId","in":"path","description":"The unique id of the location","required":true,"type":"number"},{"name":"from","in":"query","description":"The date from which measures are requested in ISO 8601 format with UTC offset (basic format, e.g 20220328T120500Z)","required":true,"type":"string"},{"name":"to","in":"query","description":"The date to which measures are requested in ISO 8601 format with UTC offset (basic format, e.g 20220328T230500Z). Must be after parameter from. The from .. to interval is limited to 10 days.","required":true,"type":"string"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Measures"}},"400":{"description":"Bad request"},"401":{"description":"Not authorized"},"404":{"description":"No data available"},"422":{"description":"from .. to interval is too large"}}}},"/public/api/v1/locations/{locationIds}/measures/buckets/{bucketSize}":{"get":{"summary":"Gets the average values across a set of locations in buckets\n","operationId":"getMeasuresAverage","parameters":[{"name":"locationIds","in":"path","description":"A comma separated list of location ids, e.g. 1001, 1002, 11234","required":true,"type":"string"},{"name":"bucketSize","in":"path","description":"The size of the bucket, can be \n5 (then 5 minute buckets for the last 24h are returned)\n15 (then 15 minute buckets for the last 48h are returned)\n30 (then 30 minute buckets for the last 48h are returned)\n60 (then 1 hour buckets for the last 7 days are returned)\n","required":true,"type":"number"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Measures"}},"400":{"description":"Bad request"},"401":{"description":"Not authorized"},"404":{"description":"No data available"},"422":{"description":"from .. to interval is too large"}}}},"/public/api/v1/routes/{uuid}/measures":{"get":{"summary":"Gets merged measures history for a route by UUID","description":"Returns a merged history of extended and standard measures for the route identified by UUID, sorted by timestamp descending. The route must be shared.","operationId":"getRouteMeasuresByUuid","security":[],"parameters":[{"name":"uuid","in":"path","description":"The unique uuid of the route","required":true,"type":"string","format":"uuid"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/MergedMeasure"}}},"401":{"description":"Not authorized"},"403":{"description":"Forbidden - Route is not shared"},"404":{"description":"Route not found"}}}},"/public/api/v1/locations/{locationId}/sensor/co2/calibration":{"post":{"summary":"Triggers calibration of the co2 sensor","description":"Note that the sensor has to be in a 400ppm environment when calibration is performed.","operationId":"calibrateCo2","parameters":[{"name":"locationId","in":"path","description":"The unique id of the location","required":true,"type":"number"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad request"},"404":{"description":"Location not present or no sensor is currently linked to the location"}}}},"/public/api/v1/sensors/{serialno}/co2/calibration":{"post":{"summary":"Triggers calibration of the co2 sensor","description":"Note that the sensor has to be in a 400ppm environment when calibration is performed.","operationId":"calibrateCo2BasedOnSerial","parameters":[{"name":"serialno","in":"path","description":"The serialno of the sensor","required":true,"type":"string"}],"responses":{"200":{"description":"OK"},"400":{"description":"Bad request"},"404":{"description":"Location not present or no sensor is currently linked to the location"}}}},"/public/api/v1/locations/{locationId}/sensor/config/leds/mode":{"get":{"summary":"Gets the led mode","operationId":"getLedMode","parameters":[{"name":"locationId","in":"path","description":"The unique id of the location","required":true,"type":"number"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/LedMode"}},"400":{"description":"Bad request"},"404":{"description":"Location not present or no sensor linked to location"}}},"put":{"summary":"Updates the led mode","operationId":"UpdateLedMode","parameters":[{"name":"locationId","in":"path","description":"The unique id of the location","required":true,"type":"number"},{"in":"body","name":"body","description":"The led mode.","required":true,"schema":{"$ref":"#/definitions/LedMode"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/LedMode"}},"400":{"description":"Bad request"},"404":{"description":"Location not present or no sensor linked to location"}}}},"/public/api/v1/sensors/{serialno}/config/leds/mode":{"get":{"summary":"Gets the led mode","operationId":"getLedModeBasedOnSerial","parameters":[{"name":"serialno","in":"path","description":"The serial number of the sensor","required":true,"type":"string"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/LedMode"}},"400":{"description":"Bad request"},"404":{"description":"Location not present or no sensor linked to location"}}},"put":{"summary":"Updates the led mode","operationId":"UpdateLedModeBasedOnSerial","parameters":[{"name":"serialno","in":"path","description":"The serial number of the sensor","required":true,"type":"string"},{"in":"body","name":"body","description":"The led mode.","required":true,"schema":{"$ref":"#/definitions/LedMode"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/LedMode"}},"400":{"description":"Bad request"},"404":{"description":"Location not present or no sensor linked to location"}}}},"/public/api/v1/place":{"get":{"summary":"Returns information about the authenticated place","operationId":"getPlace","security":[{"TokenQuery":[]}],"parameters":[],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Place"}},"401":{"description":"Not authorized"},"404":{"description":"Not found"}}}}},"definitions":{"Place":{"type":"object","properties":{"id":{"type":"number","description":"The unique id of the place"},"name":{"type":"string","description":"The name of the place"},"timezoneId":{"type":"string","description":"The IANA timezone id of the place"},"countryId":{"type":"string","description":"The ISO country code of the place"},"publicName":{"type":"string","x-nullable":true,"description":"Optional public contributor name"},"publicUrl":{"type":"string","x-nullable":true,"description":"Optional public URL associated with the place"}}},"LedMode":{"type":"object","properties":{"mode":{"type":"string","enum":["co2","pm","off","default"]}}},"Measure":{"type":"object","properties":{"locationId":{"type":"number","description":"The unique id of the location, not present for averages"},"locationName":{"type":"string","description":"The name of the location as on the AG dashboard, not present for averages"},"locationType":{"type":"string","description":"The type of the location as on the AG dashboard, indoor or outdoor"},"serialno":{"type":"string","description":"The serial number of the sensor currently linked to the location, not present for averages"},"model":{"type":"string","description":"The model identifier of the sensor currently linked to the location such as I-9PSL, O-1PST, .."},"pm01":{"type":"number","format":"float","description":"The raw PM 1 value in ug / m3, rounded to 1 fraction digit"},"pm02":{"type":"number","format":"float","description":"The raw PM 2.5 value in ug / m3, rounded to 1 fraction digit"},"pm10":{"type":"number","format":"float","description":"The raw PM 10 value in ug / m3, rounded to 1 fraction digit"},"pm01_corrected":{"type":"number","format":"float","description":"The PM 1 value with correction algorithms applied in ug / m3, rounded to 1 fraction digit"},"pm02_corrected":{"type":"number","format":"float","description":"The PM 2.5 value with correction algorithms applied in ug / m3, rounded to 1 fraction digit"},"pm10_corrected":{"type":"number","format":"float","description":"The PM 10 value with correction algorithms applied in ug / m3, rounded to 1 fraction digit"},"pm003Count":{"type":"integer","description":"The number of particles with a diameter beyond 0.3 microns in 1 deciliter of air"},"atmp":{"type":"number","format":"float","description":"The ambient temperature in celsius, rounded to 1 fraction digit"},"rhum":{"type":"integer","description":"The relative humidity in percent"},"rco2":{"type":"integer","description":"The CO2 value in ppm"},"atmp_corrected":{"type":"number","format":"float","description":"The ambient temperature with correction algorithms applied in celsius, rounded to 1 fraction digit"},"rhum_corrected":{"type":"integer","description":"The relative humidity with correction algorithms applied in percent"},"rco2_corrected":{"type":"integer","description":"The CO2 value with correction algorithms applied in ppm"},"tvoc":{"type":"number","format":"float","description":"The TVOC value in ppb, provided in case that the sensor delivers an absolute value, rounded to 1 fraction digit"},"tvocIndex":{"type":"integer","description":"The value of the TVOC index, sensor model dependent"},"noxIndex":{"type":"integer","description":"The value of the NOx index, sensor model dependent"},"no2":{"type":"number","format":"float","description":"The NO2 value in ppb for model O-M-1PPSTON-CE"},"o3":{"type":"number","format":"float","description":"The O3 value in ppb for model O-M-1PPSTON-CE"},"o3WorkingElectrode":{"type":"number","format":"float","description":"The O3 working electrode value in mV for model O-M-1PPSTON-CE"},"o3AuxiliaryElectrode":{"type":"number","format":"float","description":"The O3 auxiliary electrode value in mV for model O-M-1PPSTON-CE"},"no2WorkingElectrode":{"type":"number","format":"float","description":"The NO2 working electrode value in mV for model O-M-1PPSTON-CE"},"no2AuxiliaryElectrode":{"type":"number","format":"float","description":"The NO2 auxiliary electrode value in mV for model O-M-1PPSTON-CE"},"afeTemp":{"type":"number","format":"float","description":"The analog front end temperature for model O-M-1PPSTON-CE"},"batteryVoltage":{"type":"number","format":"float","description":"The battery voltage in volts, rounded to 2 fraction digits"},"panelVoltage":{"type":"number","format":"float","description":"The solar panel voltage in volts, rounded to 2 fraction digits"},"wifi":{"type":"integer","description":"The wifi signal strength in dBm"},"datapoints":{"type":"integer","description":"The number of data points, present only for aggregated data"},"timestamp":{"type":"string","description":"Timestamp of the measures in ISO 8601 format with UTC offset, e.g. 2022-03-28T12:07:40Z"},"firmwareVersion":{"type":"string","description":"The firmware version running on the device, e.g. \"9.2.6\", not present for averages"},"longitude":{"type":"number","format":"float","description":"The longitude of the location where the measurement was taken (if available)"},"latitude":{"type":"number","format":"float","description":"The latitude of the location where the measurement was taken (if available)"},"anomalies":{"type":"array","description":"Detected anomalies for this raw measure, if available","items":{"type":"string","enum":["condensation"]}}}},"GoMeasure":{"allOf":[{"$ref":"#/definitions/Measure"},{"type":"object","properties":{"pres":{"type":"number","format":"float","description":"Pressure in hPa if available (extended measure)"},"lat":{"type":"number","format":"float","description":"Latitude from extended measures if available"},"lng":{"type":"number","format":"float","description":"Longitude from extended measures if available"},"alt":{"type":"number","format":"float","description":"Altitude in meters from extended measures if available"},"speed":{"type":"number","format":"float","description":"Speed in m/s from extended measures if available"},"hdop":{"type":"number","format":"float","description":"HDOP (Horizontal Dilution of Precision) from extended measures if available"},"motion":{"type":"integer","description":"Motion flag/value from extended measures if available"}}}]},"RouteMeasure":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"pres":{"type":"number"},"lat":{"type":"number"},"lng":{"type":"number"},"alt":{"type":"number"},"speed":{"type":"number"},"hdop":{"type":"number"},"motion":{"type":"number"}}},"MergedMeasure":{"allOf":[{"$ref":"#/definitions/RouteMeasure"},{"type":"object","properties":{"pm01":{"type":"number"},"pm02":{"type":"number"},"pm10":{"type":"number"},"atmp":{"type":"number"},"rhum":{"type":"number"},"rco2":{"type":"number"},"tvoc_index":{"type":"number"},"nox_index":{"type":"number"},"note":{"type":"string"}}}]},"Measures":{"type":"array","items":{"$ref":"#/definitions/Measure"}},"GoMeasures":{"type":"array","items":{"$ref":"#/definitions/GoMeasure"}},"TriggeredAlarm":{"type":"object","properties":{"id":{"type":"number","description":"The unique id of the alarm"},"locationId":{"type":"number","description":"The unique id of the location where the alarm was triggered. Set for alarms of type 'location'"},"alarmType":{"type":"string","description":"The type of the alarm, the possible values are 'location', 'locationGroup', 'allLocations', 'indoorLocations', 'outdoorLocations'"},"locationName":{"type":"string","description":"The name of the affected location if set"},"locationNotes":{"type":"string","description":"Notes regarding the affected location if set"},"locationGroupId":{"type":"number","description":"The id of the related group for alarms of type 'locationGroup'"},"locationGroupName":{"type":"string","description":"The name of the related group for alarms of type 'locationGroup'"},"title":{"type":"string","description":"The title of the alarm"},"description":{"type":"string","description":"The description of the alarm"},"measure":{"type":"string","description":"The measure that triggered the alarm"},"indoor":{"type":"boolean","description":"True if the alarm is related to an indoor location"},"locations":{"type":"array","items":{"$ref":"#/definitions/TriggeredAlarmLocationState"},"description":"The list of locations that triggered the alarm in case that the alarm is of a type that supports multiple locations, e.g.  'allLocations', 'indoorLocations', ..."}}},"TriggeredAlarmLocationState":{"type":"object","properties":{"locationId":{"type":"number","description":"The unique id of the location"},"locationName":{"type":"string","description":"The name of the location"},"state":{"type":"string","enum":["idle","armed","triggered"],"description":"The state of the alarm"}},"additionalProperties":true},"TriggeredAlarms":{"type":"array","items":{"$ref":"#/definitions/TriggeredAlarm"}}}}