Skip to content
OpenAQ Docs

Get locations

GET
/v3/locations
 
curl --request GET \
  --url 'https://example.com/v3/locations?coordinates=38.907%2C-77.037&radius=1000&providers_id=1&limit=100&page=1&order_by=id&sort_order=asc&iso=US&countries_id=1&bbox=-77.1200%2C38.7916%2C-76.9094%2C38.9955' \
  --header 'X-API-Key: <X-API-Key>'

Provides a list of locations

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
coordinates
Any of:
string

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

radius
Any of:
integer
> 0 <= 25000

Search radius from coordinates as center in meters. Maximum of 25,000 (25km) defaults to 1000 (1km) e.g. radius=1000

providers_id
Any of:
Array<integer>

Limit the results to a specific provider or multiple providers with a single provider ID or a comma delimited list of IDs

parameters_id
Any of:
Array<integer>
limit
Limit

Change the number of results returned. e.g. limit=100 will return up to 100 results

integer
default: 100

Change the number of results returned. e.g. limit=100 will return up to 100 results

page
Page

Paginate through results. e.g. page=1 will return first page of results

integer
default: 1

Paginate through results. e.g. page=1 will return first page of results

owner_contacts_id
Any of:
Array<integer>

Limit the results to a specific owner by owner ID with a single owner ID or comma delimited list of IDs

manufacturers_id
Any of:
Array<integer>
order_by
Any of:
LocationsSortFields
string
Allowed values: id

The field by which to order results

sort_order
Any of:
SortOrder
string
Allowed values: asc desc

Sort results ascending or descending. Default ASC

licenses_id
Any of:
Array<integer>
monitor
Any of:
boolean

Is the location considered a reference monitor?

mobile
Any of:
boolean

Is the location considered a mobile location?

instruments_id
Any of:
Array<integer>
iso
Any of:
string

Limit the results to a specific country using ISO 3166-1 alpha-2 code

countries_id
Any of:
Array<integer>

Limit the results to a specific country or countries by country ID as a single country ID or a comma delimited list of IDs

bbox
Any of:
string

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

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

Media type application/json
LocationsResponse
object
meta
Meta
object
name
Name
string
default: openaq-api
website
Website
string
default: /
page
Page
integer
default: 1
limit
Limit
integer
default: 100
found
Any of:
integer
results
required
Results
Array<object>
Location
object
id
required
Id
integer
name
Any of:
string
locality
Any of:
string
timezone
required
Timezone
string
country
required
CountryBase
object
id
Any of:
integer
code
required
Code
string
name
required
Name
string
owner
required
EntityBase
object
id
required
Id
integer
name
required
Name
string
provider
required
ProviderBase
object
id
required
Id
integer
name
required
Name
string
isMobile
required
Ismobile
boolean
isMonitor
required
Ismonitor
boolean
instruments
required
Instruments
Array<object>
InstrumentBase
object
id
required
Id
integer
name
required
Name
string
sensors
required
Sensors
Array<object>
SensorBase
object
id
required
Id
integer
name
required
Name
string
parameter
required
ParameterBase
object
id
required
Id
integer
name
required
Name
string
units
required
Units
string
displayName
Any of:
string
coordinates
required
Coordinates
object
latitude
Any of:
number
longitude
Any of:
number
licenses
Any of:
Array<object>
LocationLicense
object
id
required
Id
integer
name
required
Name
string
attribution
required
AttributionEntity
object
name
required
Name
string
url
Any of:
string
dateFrom
Any of:
string format: date
dateTo
Any of:
string format: date
bounds
required
Bounds
Array<number>
>= 4 items <= 4 items
distance
Any of:
number
datetimeFirst
Any of:
DatetimeObject
object
utc
required
Utc
string format: date-time
local
required
Local
string format: date-time
datetimeLast
Any of:
DatetimeObject
object
utc
required
Utc
string format: date-time
local
required
Local
string format: date-time
Example 
{
  "meta": {
    "name": "openaq-api",
    "website": "/",
    "page": 1,
    "limit": 100
  }
}

422

Section titled “422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Example generated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}