OpenAQ Locations API
The Locations API from OpenAQ — 11 operation(s) for locations.
OpenAPI Specification
openapi: 3.1.0
info:
title: OpenAQ Averages Locations API
description: '
OpenAQ is a nonprofit organization providing universal access to air
quality data to empower a global community of changemakers to solve air
inequality-the unequal access to clean air.'
version: 2.0.0
tags:
- name: Locations
paths:
/v3/locations/{locations_id}:
get:
tags:
- Locations
summary: OpenAQ Get a location by ID
description: Provides a location by location ID
operationId: location_get_v3_locations__locations_id__get
security:
- APIKeyHeader: []
parameters:
- name: locations_id
in: path
required: true
schema:
type: integer
description: Limit the results to a specific location by id
title: Locations Id
description: Limit the results to a specific location by id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/openaq_api__v3__models__responses__LocationsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v3/locations:
get:
tags:
- Locations
summary: OpenAQ Get locations
description: Provides a list of locations
operationId: locations_get_v3_locations_get
security:
- APIKeyHeader: []
parameters:
- name: coordinates
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: WGS 84 Coordinate pair in form latitude,longitude. Supports up to 4 decimal points of precision, additional decimal precision will be truncated in the query e.g. 38.9074,-77.0373
examples:
- 38.907,-77.037
title: Coordinates
description: WGS 84 Coordinate pair in form latitude,longitude. Supports up to 4 decimal points of precision, additional decimal precision will be truncated in the query e.g. 38.9074,-77.0373
- name: radius
in: query
required: false
schema:
anyOf:
- type: integer
maximum: 25000
exclusiveMinimum: 0
- type: 'null'
description: Search radius from coordinates as center in meters. Maximum of 25,000 (25km) defaults to 1000 (1km) e.g. radius=1000
examples:
- '1000'
title: Radius
description: Search radius from coordinates as center in meters. Maximum of 25,000 (25km) defaults to 1000 (1km) e.g. radius=1000
- name: providers_id
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: Limit the results to a specific provider or multiple providers with a single provider ID or a comma delimited list of IDs
examples:
- '1'
- 1,2,3
title: Providers Id
description: Limit the results to a specific provider or multiple providers with a single provider ID or a comma delimited list of IDs
- name: parameters_id
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
title: Parameters Id
- name: limit
in: query
required: false
schema:
type: integer
description: "Change the number of results returned.\n e.g. limit=100 will return up to 100 results"
examples:
- '100'
default: 100
title: Limit
description: "Change the number of results returned.\n e.g. limit=100 will return up to 100 results"
- name: page
in: query
required: false
schema:
type: integer
description: Paginate through results. e.g. page=1 will return first page of results
examples:
- '1'
default: 1
title: Page
description: Paginate through results. e.g. page=1 will return first page of results
- name: owner_contacts_id
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: Limit the results to a specific owner by owner ID with a single owner ID or comma delimited list of IDs
title: Owner Contacts Id
description: Limit the results to a specific owner by owner ID with a single owner ID or comma delimited list of IDs
- name: manufacturers_id
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
title: Manufacturers Id
- name: order_by
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/LocationsSortFields'
- type: 'null'
description: The field by which to order results
examples:
- order_by=id
default: id
title: Order By
description: The field by which to order results
- name: sort_order
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/SortOrder'
- type: 'null'
description: Sort results ascending or descending. Default ASC
examples:
- sort=desc
default: asc
title: Sort Order
description: Sort results ascending or descending. Default ASC
- name: licenses_id
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
title: Licenses Id
- name: monitor
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Is the location considered a reference monitor?
title: Monitor
description: Is the location considered a reference monitor?
- name: mobile
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Is the location considered a mobile location?
title: Mobile
description: Is the location considered a mobile location?
- name: instruments_id
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
title: Instruments Id
- name: iso
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Limit the results to a specific country using ISO 3166-1 alpha-2 code
examples:
- US
title: Iso
description: Limit the results to a specific country using ISO 3166-1 alpha-2 code
- name: countries_id
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: Limit the results to a specific country or countries by country ID as a single country ID or a comma delimited list of IDs
examples:
- '1'
- 1,2,3
title: Countries Id
description: Limit the results to a specific country or countries by country ID as a single country ID or a comma delimited list of IDs
- name: bbox
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: geospatial bounding box of Min X, min Y, max X, max Y in WGS 84 coordinates. Up to 4 decimal points of precision, addtional decimal precision will be truncated to 4 decimal points precision e.g. -77.037,38.907,-77.0,39.910
examples:
- -77.1200,38.7916,-76.9094,38.9955
title: Bbox
description: geospatial bounding box of Min X, min Y, max X, max Y in WGS 84 coordinates. Up to 4 decimal points of precision, addtional decimal precision will be truncated to 4 decimal points precision e.g. -77.037,38.907,-77.0,39.910
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/openaq_api__v3__models__responses__LocationsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v3/locations/{locations_id}/sensors:
get:
tags:
- Locations
summary: OpenAQ Get sensors by location ID
description: Provides a list of sensors by location ID
operationId: sensors_get_v3_locations__locations_id__sensors_get
security:
- APIKeyHeader: []
parameters:
- name: locations_id
in: path
required: true
schema:
type: integer
description: Limit the results to a specific sensors id
title: Locations Id
description: Limit the results to a specific sensors id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SensorsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v3/locations/{locations_id}/latest:
get:
tags:
- Locations
summary: OpenAQ Get a location's latest measurements
description: Providers a location's latest measurement values
operationId: location_latest_get_v3_locations__locations_id__latest_get
security:
- APIKeyHeader: []
parameters:
- name: locations_id
in: path
required: true
schema:
type: integer
description: Limit the results to a specific location by id
title: Locations Id
description: Limit the results to a specific location by id
- name: limit
in: query
required: false
schema:
type: integer
description: "Change the number of results returned.\n e.g. limit=100 will return up to 100 results"
examples:
- '100'
default: 100
title: Limit
description: "Change the number of results returned.\n e.g. limit=100 will return up to 100 results"
- name: page
in: query
required: false
schema:
type: integer
description: Paginate through results. e.g. page=1 will return first page of results
examples:
- '1'
default: 1
title: Page
description: Paginate through results. e.g. page=1 will return first page of results
- name: datetime_min
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: string
format: date
- type: 'null'
description: Minimum datetime
examples:
- '2022-10-01T11:19:38-06:00'
- '2022-10-01'
title: Datetime Min
description: Minimum datetime
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/openaq_api__v3__models__responses__LatestResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v3/locations/{locations_id}/flags:
get:
tags:
- Locations
summary: OpenAQ Get flags by location ID
description: Provides a list of flags by location ID
operationId: location_flags_get_v3_locations__locations_id__flags_get
security:
- APIKeyHeader: []
parameters:
- name: locations_id
in: path
required: true
schema:
type: integer
description: Limit the results to a specific locations
title: Locations Id
description: Limit the results to a specific locations
- name: limit
in: query
required: false
schema:
type: integer
description: "Change the number of results returned.\n e.g. limit=100 will return up to 100 results"
examples:
- '100'
default: 100
title: Limit
description: "Change the number of results returned.\n e.g. limit=100 will return up to 100 results"
- name: page
in: query
required: false
schema:
type: integer
description: Paginate through results. e.g. page=1 will return first page of results
examples:
- '1'
default: 1
title: Page
description: Paginate through results. e.g. page=1 will return first page of results
- name: datetime_from
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: string
format: date
- type: 'null'
description: To when?
examples:
- '2022-10-01T11:19:38-06:00'
- '2022-10-01'
title: Datetime From
description: To when?
- name: datetime_to
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: string
format: date
- type: 'null'
description: To when?
examples:
- '2022-10-01T11:19:38-06:00'
- '2022-10-01'
title: Datetime To
description: To when?
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LocationFlagsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v2/locations/{location_id}:
get:
tags:
- Locations
summary: OpenAQ Get a location by ID
description: Provides a location by location ID
operationId: get_v2_location_by_id_v2_locations__location_id__get
deprecated: true
security:
- APIKeyHeader: []
parameters:
- name: location_id
in: path
required: true
schema:
type: integer
description: The ID of the location
title: Location Id
description: The ID of the location
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
examples:
- '1000'
default: 100
title: Limit
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
- name: page
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Paginate through results. e.g. page=1 will return first page of results
examples:
- '1'
default: 1
title: Page
description: Paginate through results. e.g. page=1 will return first page of results
- name: offset
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
default: 0
title: Offset
- name: sort
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/Sort'
- type: 'null'
description: Define sort order. e.g. ?sort=asc
default: asc
title: Sort
description: Define sort order. e.g. ?sort=asc
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/openaq_api__models__responses__LocationsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v2/locations:
get:
tags:
- Locations
summary: OpenAQ Get locations
description: Provides a list of locations
operationId: locations_get_v2_locations_get
deprecated: true
security:
- APIKeyHeader: []
parameters:
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
examples:
- '1000'
default: 100
title: Limit
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
- name: page
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Paginate through results. e.g. page=1 will return first page of results
examples:
- '1'
default: 1
title: Page
description: Paginate through results. e.g. page=1 will return first page of results
- name: offset
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
default: 0
title: Offset
- name: sort
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/Sort'
- type: 'null'
description: Sort Direction e.g. sort=desc
examples:
- desc
default: desc
title: Sort
description: Sort Direction e.g. sort=desc
- name: parameter_id
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: (optional) A parameter ID to filter measurement results. e.g. parameter_id=2 (i.e. PM2.5) will limit measurement results to only PM2.5 measurements
examples:
- '2'
title: Parameter Id
description: (optional) A parameter ID to filter measurement results. e.g. parameter_id=2 (i.e. PM2.5) will limit measurement results to only PM2.5 measurements
- name: parameter
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: (optional) A parameter name or ID by which to filter measurement results. e.g. parameter=pm25 or parameter=pm25¶meter=pm10
examples:
- pm25
title: Parameter
description: (optional) A parameter name or ID by which to filter measurement results. e.g. parameter=pm25 or parameter=pm25¶meter=pm10
- name: unit
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
title: Unit
- name: coordinates
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Coordinate pair in form lat,lng. Up to 8 decimal points of precision e.g. 38.907,-77.037
examples:
- 38.907,-77.037
title: Coordinates
description: Coordinate pair in form lat,lng. Up to 8 decimal points of precision e.g. 38.907,-77.037
- name: radius
in: query
required: false
schema:
type: integer
description: Search radius from coordinates as center in meters. Maximum of 25,000 (25km) defaults to 1000 (1km) e.g. radius=10000
examples:
- '10000'
default: 1000
title: Radius
description: Search radius from coordinates as center in meters. Maximum of 25,000 (25km) defaults to 1000 (1km) e.g. radius=10000
- name: country_id
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Limit results by a certain country using two digit country ID. e.g. 13
examples:
- 13
title: Country Id
description: Limit results by a certain country using two digit country ID. e.g. 13
- name: country
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Limit results by a certain country using two letter country code. e.g. ?country=US or ?country=US&country=MX
examples:
- US
title: Country
description: Limit results by a certain country using two letter country code. e.g. ?country=US or ?country=US&country=MX
- name: city
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Limit results by a certain city or cities. (e.g. ?city=Chicago or ?city=Chicago&city=Boston)
examples:
- Chicago
title: City
description: Limit results by a certain city or cities. (e.g. ?city=Chicago or ?city=Chicago&city=Boston)
- name: location_id
in: query
required: false
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
title: Location Id
- name: location
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
title: Location
- name: order_by
in: query
required: false
schema:
allOf:
- $ref: '#/components/schemas/LocationsOrder'
description: Order by a field
default: lastUpdated
title: Order By
description: Order by a field
- name: is_mobile
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Location is mobile e.g. ?isMobile=true
examples:
- 'true'
title: Is Mobile
description: Location is mobile e.g. ?isMobile=true
- name: is_analysis
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: 'Data is the product of a previous analysis/aggregation and not raw measurements e.g. ?isAnalysis=true '
examples:
- 'true'
title: Is Analysis
description: 'Data is the product of a previous analysis/aggregation and not raw measurements e.g. ?isAnalysis=true '
- name: source_name
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Name of the data source e.g. ?sourceName=Houston%20Mobile
examples:
- Houston%20Mobile
title: Source Name
description: Name of the data source e.g. ?sourceName=Houston%20Mobile
- name: entity
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/EntityTypes'
- type: 'null'
description: Source entity type. e.g. ?entity=government
examples:
- government
title: Entity
description: Source entity type. e.g. ?entity=government
- name: sensor_type
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/SensorTypes'
- type: 'null'
description: Type of Sensor e.g. ?sensorType=reference%20grade
examples:
- reference%20grade
title: Sensor Type
description: Type of Sensor e.g. ?sensorType=reference%20grade
- name: model_name
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Model Name of Sensor e.g. ?modelName=AE33
examples:
- AE33
title: Model Name
description: Model Name of Sensor e.g. ?modelName=AE33
- name: manufacturer_name
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Manufacturer of Sensor e.g. ?manufacturer=Ecotech
examples:
- Ecotech
title: Manufacturer Name
description: Manufacturer of Sensor e.g. ?manufacturer=Ecotech
- name: dump_raw
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
default: false
title: Dump Raw
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/openaq_api__models__responses__LocationsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v2/latest/{location_id}:
get:
tags:
- Locations
summary: OpenAQ Get latest measurements by location ID
description: Provides latest measurements for a locations by location ID
operationId: get_v2_latest_by_id_v2_latest__location_id__get
deprecated: true
security:
- APIKeyHeader: []
parameters:
- name: location_id
in: path
required: true
schema:
type: integer
description: The ID of the location
title: Location Id
description: The ID of the location
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
examples:
- '1000'
default: 100
title: Limit
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
- name: page
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Paginate through results. e.g. page=1 will return first page of results
examples:
- '1'
default: 1
title: Page
description: Paginate through results. e.g. page=1 will return first page of results
- name: offset
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
default: 0
title: Offset
- name: sort
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/Sort'
- type: 'null'
description: Define sort order. e.g. ?sort=asc
default: asc
title: Sort
description: Define sort order. e.g. ?sort=asc
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/openaq_api__models__responses__LatestResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/latest/{location_id}:
get:
tags:
- Locations
summary: OpenAQ Get latest measurements by location ID
operationId: get_v1_latest_by_id_v1_latest__location_id__get
deprecated: true
security:
- APIKeyHeader: []
parameters:
- name: location_id
in: path
required: true
schema:
type: integer
description: The ID of the location
title: Location Id
description: The ID of the location
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
examples:
- '1000'
default: 100
title: Limit
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
- name: page
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Paginate through results. e.g. page=1 will return first page of results
examples:
- '1'
default: 1
title: Page
description: Paginate through results. e.g. page=1 will return first page of results
- name: offset
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
default: 0
title: Offset
- name: sort
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/Sort'
- type: 'null'
description: Define sort order. e.g. ?sort=asc
default: asc
title: Sort
description: Define sort order. e.g. ?sort=asc
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LatestResponseV1'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/locations/{location_id}:
get:
tags:
- Locations
summary: OpenAQ Get location by ID
operationId: get_v1_locations_by_id_v1_locations__location_id__get
deprecated: true
security:
- APIKeyHeader: []
parameters:
- name: location_id
in: path
required: true
schema:
type: integer
description: The ID of the location
title: Location Id
description: The ID of the location
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
examples:
- '1000'
default: 100
title: Limit
description: Change the number of results returned. e.g. limit=1000 will return up to 1000 results
- name: page
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Paginate through results. e.g. page=1 will return first page of results
examples:
- '1'
default: 1
title: Page
description: Paginate through results. e.g. page=1 will return first page of results
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openaq/refs/heads/main/openapi/openaq-locations-api-openapi.yml