Google Maps Platform Air Quality Forecast API

The Air Quality Forecast API from Google Maps Platform — 1 operation(s) for air quality forecast.

GitHub OpenAPI

Operations 1

POST /v1/forecast:lookup Lookup forecast #

Documentation

Specifications

Schemas & Data

Other Resources

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/google-maps:google-maps-air-quality-forecast-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

google-maps-air-quality-forecast-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Air Quality API Forecast Air Quality Forecast API
  version: v1
  description: Generated from Google's published Discovery document for Air Quality API (airquality v1, revision 20261111). 1 operation(s).
  contact:
    name: Google
    url: https://developers.google.com/
  termsOfService: https://developers.google.com/terms
servers:
- url: https://airquality.googleapis.com
tags:
- name: Air Quality Forecast
paths:
  /v1/forecast:lookup:
    post:
      operationId: airquality.forecast.lookup
      summary: Lookup forecast
      description: Returns air quality forecast for a specific location for a given time range.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupForecastRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupForecastResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
      - apiKey: []
      tags:
      - Air Quality Forecast
components:
  schemas:
    AdditionalInfo:
      properties:
        sources:
          description: Text representing the pollutant's main emission sources.
          type: string
        effects:
          type: string
          description: Text representing the pollutant's main health effects.
      description: The emission sources and health effects of a given pollutant.
      type: object
    Color:
      description: 'Represents a color in the RGBA color space. This representation is designed for simplicity of conversion to and from color representations in various languages over compactness. For example, the fields of this representation can be trivially provided to the constructor of `java.awt.Color` in Java; it can also be trivially provided to UIColor''s `+colorWithRed:green:blue:alpha` method in iOS; and, with just a little work, it can be easily formatted into a CSS `rgba()` string in JavaScript. This reference page doesn''t have information about the absolute color space that should be used to interpret the RGB value—for example, sRGB, Adobe RGB, DCI-P3, and BT.2020. By default, applications should assume the sRGB color space. When color equality needs to be decided, implementations, unless documented otherwise, treat two colors as equal if all their red, green, blue, and alpha values each differ by at most `1e-5`. Example (Java): import com.google.type.Color; // ... public static java.awt.Color fromProto(Color protocolor) { float alpha = protocolor.hasAlpha() ? protocolor.getAlpha().getValue() : 1.0; return new java.awt.Color( protocolor.getRed(), protocolor.getGreen(), protocolor.getBlue(), alpha); } public static Color toProto(java.awt.Color color) { float red = (float) color.getRed(); float green = (float) color.getGreen(); float blue = (float) color.getBlue(); float denominator = 255.0; Color.Builder resultBuilder = Color .newBuilder() .setRed(red / denominator) .setGreen(green / denominator) .setBlue(blue / denominator); int alpha = color.getAlpha(); if (alpha != 255) { result.setAlpha( FloatValue .newBuilder() .setValue(((float) alpha) / denominator) .build()); } return resultBuilder.build(); } // ... Example (iOS / Obj-C): // ... static UIColor* fromProto(Color* protocolor) { float red = [protocolor red]; float green = [protocolor green]; float blue = [protocolor blue]; FloatValue* alpha_wrapper = [protocolor alpha]; float alpha = 1.0; if (alpha_wrapper != nil) { alpha = [alpha_wrapper value]; } return [UIColor colorWithRed:red green:green blue:blue alpha:alpha]; } static Color* toProto(UIColor* color) { CGFloat red, green, blue, alpha; if (![color getRed:&red green:&green blue:&blue alpha:&alpha]) { return nil; } Color* result = [[Color alloc] init]; [result setRed:red]; [result setGreen:green]; [result setBlue:blue]; if (alpha <= 0.9999) { [result setAlpha:floatWrapperWithValue(alpha)]; } [result autorelease]; return result; } // ... Example (JavaScript): // ... var protoToCssColor = function(rgb_color) { var redFrac = rgb_color.red || 0.0; var greenFrac = rgb_color.green || 0.0; var blueFrac = rgb_color.blue || 0.0; var red = Math.floor(redFrac * 255); var green = Math.floor(greenFrac * 255); var blue = Math.floor(blueFrac * 255); if (!(''alpha'' in rgb_color)) { return rgbToCssColor(red, green, blue); } var alphaFrac = rgb_color.alpha.value || 0.0; var rgbParams = [red, green, blue].join('',''); return [''rgba('', rgbParams, '','', alphaFrac, '')''].join(''''); }; var rgbToCssColor = function(red, green, blue) { var rgbNumber = new Number((red << 16) | (green << 8) | blue); var hexString = rgbNumber.toString(16); var missingZeros = 6 - hexString.length; var resultBuilder = [''#'']; for (var i = 0; i < missingZeros; i++) { resultBuilder.push(''0''); } resultBuilder.push(hexString); return resultBuilder.join(''''); }; // ...'
      properties:
        alpha:
          format: float
          description: 'The fraction of this color that should be applied to the pixel. That is, the final pixel color is defined by the equation: `pixel color = alpha * (this color) + (1.0 - alpha) * (background color)` This means that a value of 1.0 corresponds to a solid color, whereas a value of 0.0 corresponds to a completely transparent color. This uses a wrapper message rather than a simple float scalar so that it is possible to distinguish between a default value and the value being unset. If omitted, this color object is rendered as a solid color (as if the alpha value had been explicitly given a value of 1.0).'
          type: number
        blue:
          description: The amount of blue in the color as a value in the interval [0, 1].
          type: number
          format: float
        green:
          description: The amount of green in the color as a value in the interval [0, 1].
          format: float
          type: number
        red:
          description: The amount of red in the color as a value in the interval [0, 1].
          format: float
          type: number
      type: object
    Interval:
      description: Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive). The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time.
      type: object
      properties:
        startTime:
          type: string
          format: google-datetime
          description: Optional. Inclusive start of the interval. If specified, a Timestamp matching this interval will have to be the same or after the start.
        endTime:
          description: Optional. Exclusive end of the interval. If specified, a Timestamp matching this interval will have to be before the end.
          type: string
          format: google-datetime
    CustomLocalAqi:
      properties:
        regionCode:
          type: string
          description: The country/region requiring the custom AQI. Value should be provided using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code.
        aqi:
          type: string
          description: The AQI to associate the country/region with. Value should be a [valid index](/maps/documentation/air-quality/laqis) code.
      description: Expresses a 'country/region to AQI' relationship. Pairs a country/region with a desired AQI so that air quality data that is required for that country/region will be displayed according to the chosen AQI.
      type: object
    GoogleRpcError:
      type: object
      description: The error envelope every Google API returns.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            status:
              type: string
            details:
              type: array
              items:
                type: object
    LookupForecastRequest:
      type: object
      properties:
        pageToken:
          description: Optional. A page token received from a previous forecast call. It is used to retrieve the subsequent page.
          type: string
        uaqiColorPalette:
          description: Optional. Determines the color palette used for data provided by the 'Universal Air Quality Index' (UAQI). This color palette is relevant just for UAQI, other AQIs have a predetermined color palette that can't be controlled.
          type: string
          enum:
          - COLOR_PALETTE_UNSPECIFIED
          - RED_GREEN
          - INDIGO_PERSIAN_DARK
          - INDIGO_PERSIAN_LIGHT
        dateTime:
          description: 'A timestamp for which to return the data for a specific point in time. The timestamp is rounded to the previous exact hour. Note: this will return hourly data for the requested timestamp only (i.e. a single hourly info element). For example, a request sent where the date_time parameter is set to 2023-01-03T11:05:49Z will be rounded down to 2023-01-03T11:00:00Z.'
          type: string
          format: google-datetime
        languageCode:
          type: string
          description: Optional. Allows the client to choose the language for the response. If data cannot be provided for that language the API uses the closest match. Allowed values rely on the IETF standard (default = 'en').
        extraComputations:
          items:
            enum:
            - EXTRA_COMPUTATION_UNSPECIFIED
            - LOCAL_AQI
            - HEALTH_RECOMMENDATIONS
            - POLLUTANT_ADDITIONAL_INFO
            - DOMINANT_POLLUTANT_CONCENTRATION
            - POLLUTANT_CONCENTRATION
            type: string
          type: array
          description: Optional. Additional features that can be optionally enabled. Specifying extra computations will result in the relevant elements and fields to be returned in the response.
        customLocalAqis:
          type: array
          items:
            $ref: '#/components/schemas/CustomLocalAqi'
          description: Optional. Expresses a 'country/region to AQI' relationship. Pairs a country/region with a desired AQI so that air quality data that is required for that country/region will be displayed according to the chosen AQI. This parameter can be used to specify a non-default AQI for a given country, for example, to get the US EPA index for Canada rather than the default index for Canada.
        universalAqi:
          description: Optional. If set to true, the Universal AQI will be included in the 'indexes' field of the response (default = true).
          type: boolean
        pageSize:
          type: integer
          description: Optional. The maximum number of hourly info records to return per page (default = 24).
          format: int32
        period:
          $ref: '#/components/schemas/Interval'
          description: Indicates the start and end period for which to get the forecast data. The timestamp is rounded to the previous exact hour.
        location:
          $ref: '#/components/schemas/LatLng'
          description: Required. The latitude and longitude for which the API looks for air quality data.
      description: The request object of the air quality forecast API.
    Concentration:
      description: The concentration of a given pollutant in the air.
      type: object
      properties:
        units:
          type: string
          enum:
          - UNIT_UNSPECIFIED
          - PARTS_PER_BILLION
          - MICROGRAMS_PER_CUBIC_METER
          description: Units for measuring this pollutant concentration.
        value:
          description: Value of the pollutant concentration.
          type: number
          format: float
    HealthRecommendations:
      description: Health recommendations for different population groups in a free text format. The recommendations are derived from their associated air quality conditions.
      properties:
        heartDiseasePopulation:
          type: string
          description: Heart and circulatory system diseases.
        athletes:
          type: string
          description: Sports and other strenuous outdoor activities.
        lungDiseasePopulation:
          description: Respiratory related problems and asthma suffers.
          type: string
        children:
          type: string
          description: Younger populations including children, toddlers, and babies.
        pregnantWomen:
          type: string
          description: Women at all stages of pregnancy.
        elderly:
          type: string
          description: Retirees and people older than the general population.
        generalPopulation:
          description: No specific sensitivities.
          type: string
      type: object
    LatLng:
      description: An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.
      properties:
        longitude:
          type: number
          format: double
          description: The longitude in degrees. It must be in the range [-180.0, +180.0].
        latitude:
          description: The latitude in degrees. It must be in the range [-90.0, +90.0].
          type: number
          format: double
      type: object
    AirQualityIndex:
      type: object
      properties:
        aqi:
          type: integer
          format: int32
          description: ' The index''s numeric score. Examples: 10, 100. The value is not normalized and should only be interpreted in the context of its related air-quality index. For non-numeric indexes, this field will not be returned. Note: This field should be used for calculations, graph display, etc. For displaying the index score, you should use the AQI display field.'
        category:
          description: 'Textual classification of the index numeric score interpretation. For example: "Excellent air quality".'
          type: string
        code:
          description: 'The index''s code. This field represents the index for programming purposes by using snake case instead of spaces. Examples: "uaqi", "fra_atmo".'
          type: string
        aqiDisplay:
          type: string
          description: 'Textual representation of the index numeric score, that may include prefix or suffix symbols, which usually represents the worst index score. Example: >100 or 10+. Note: This field should be used when you want to display the index score. For non-numeric indexes, this field is empty.'
        dominantPollutant:
          description: 'The chemical symbol of the dominant pollutant. For example: "CO".'
          type: string
        color:
          $ref: '#/components/schemas/Color'
          description: The color used to represent the AQI numeric score.
        displayName:
          type: string
          description: 'A human readable representation of the index name. Example: "AQI (US)"'
      description: The basic object for representing different air quality metrics. When brought together, these metrics provide a snapshot about the current air quality conditions. There are multiple indexes in the world serving different purposes and groups interested in measuring different aspects of air quality.
    Pollutant:
      type: object
      properties:
        additionalInfo:
          $ref: '#/components/schemas/AdditionalInfo'
          description: Additional information about the pollutant.
        code:
          description: The pollutant's code name (for example, "so2"). For a list of supported pollutant codes, see [Reported pollutants](/maps/documentation/air-quality/pollutants#reported_pollutants).
          type: string
        concentration:
          $ref: '#/components/schemas/Concentration'
          description: The pollutant's concentration level measured by one of the standard air pollutation measure units.
        displayName:
          type: string
          description: 'The pollutant''s display name. For example: "NOx".'
        fullName:
          description: 'The pollutant''s full name. For chemical compounds, this is the IUPAC name. Example: "Sulfur Dioxide". For more information about the IUPAC names table, see https://iupac.org/what-we-do/periodic-table-of-elements/.'
          type: string
      description: Data regarding an air quality pollutant.
    LookupForecastResponse:
      properties:
        nextPageToken:
          type: string
          description: Optional. The token to retrieve the next page.
        regionCode:
          description: Optional. The ISO_3166-1 alpha-2 code of the country/region corresponding to the location provided in the request. This field might be omitted from the response if the location provided in the request resides in a disputed territory.
          type: string
        hourlyForecasts:
          description: Optional. Contains the air quality information for each hour in the requested range. For example, if the request is for 48 hours of forecast there will be 48 elements of hourly forecasts.
          type: array
          items:
            $ref: '#/components/schemas/HourlyForecast'
      description: The response object of the air quality forecast API.
      type: object
    HourlyForecast:
      properties:
        healthRecommendations:
          $ref: '#/components/schemas/HealthRecommendations'
          description: Health advice and recommended actions related to the reported air quality conditions. Recommendations are tailored differently for populations at risk, groups with greater sensitivities to pollutants, and the general population.
        indexes:
          description: 'Based on the request parameters, this list will include (up to) two air quality indexes: - Universal AQI. Will be returned if the `universal_aqi` boolean is set to true. - Local AQI. Will be returned if the LOCAL_AQI extra computation is specified.'
          type: array
          items:
            $ref: '#/components/schemas/AirQualityIndex'
        dateTime:
          format: google-datetime
          type: string
          description: 'A rounded down timestamp indicating the time (hour) the data refers to in RFC3339 UTC "Zulu" format. For example: "2014-10-02T15:00:00Z".'
        pollutants:
          items:
            $ref: '#/components/schemas/Pollutant'
          description: 'A list of pollutants affecting the location specified in the request. Note: This field will be returned only for requests that specified one or more of the following extra computations: POLLUTANT_ADDITIONAL_INFO, DOMINANT_POLLUTANT_CONCENTRATION, POLLUTANT_CONCENTRATION.'
          type: array
      type: object
      description: Contains the air quality information for each hour in the requested range. For example, if the request is for 48 hours of forecast there will be 48 elements of hourly forecasts.
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: API key; accepted by methods that do not need user data.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/cloud-platform: See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account.
externalDocs:
  url: https://developers.google.com/maps/documentation/air-quality
x-provenance:
  method: harvested
  publisher: Google
  source: https://airquality.googleapis.com/$discovery/rest?version=v1
  note: converted by discovery-to-openapi.py from Google's Discovery document (revision 20261111)