Air quality awareness for Places using Air Quality API
Stay organized with collections
Save and categorize content based on your preferences.
In this document, you will look into how to use Air Quality API to build rich place search experiences.
We will show how air quality can be a signal of value for users from the very beginning
until the end of the funnel and how Air Quality API data can be embedded into existing experiences.
Use Cases and added value
Air Quality API signals can fit into various search experiences such as
when users are looking for a location to visit. Air Quality API offers:
Real time * and historical data - fresh, accurate data that represents the current state as well as back in time data within a 30 days window in an hourly resolution. (* an hourly snapshot of outdoor air quality)
Global and local data - covering entire areas in 100+ countries yet highly localized (up to 500m) Air Quality API data provides key signals for users to compare and make decisions on the most appropriate place.
Air quality can be drastically different even for near locations
Sample Walkthrough
Show air quality data early in the experience
There are two main ways to show the Air Quality API data:
Choose your location index: Universal AQI or a Local AQI (up to 70 different Air Quality Indexes (AQI) are available). An air quality index (AQI) is the scale by which a certain country, for example, the U.S. EPA, categorizes different air quality levels, based on different calculation methods, data sources, and designated purposes.
Start visualizing the main Air Quality API value and color code straight from the place search experience.
default display could include the color code only.
Pollutant levels, which are a measure of particles and gasses in the air: Dominant pollutant, Concentration, Sources & Effects.
Health recommendations, which are recommended actions for current air quality conditions.
You can adjust the level of information displayed by default to serve your needs. Keep in mind that data points for a location are often useful in comparison to other locations.
Air quality section display example
Air Quality Response
{
"dateTime": "2023-08-09T10:00:00Z",
"regionCode": "fr",
"indexes": [
{
"code": "uaqi",
"displayName": "Universal AQI",
"aqi": 76,
"aqiDisplay": "76",
"color": {
"red": 0.4117647,
"green": 0.77254903,
"blue": 0.20392157
},
"category": "Good air quality",
"dominantPollutant": "pm10"
},
…
],
"pollutants": [
{
"code": "co",
"displayName": "CO",
"fullName": "Carbon monoxide",
"concentration": {
"value": 95.18,
"units": "PARTS_PER_BILLION"
}...
},
…
],
"healthRecommendations": -{
"generalPopulation": "With this level of air quality, you have no limitations. Enjoy the outdoors!",
"elderly": "If you start to feel respiratory discomfort such as coughing or breathing difficulties, consider red ...",
"lungDiseasePopulation": …
}
}
Alternatively, you can query Air Quality data only on interaction with a location.
You can use Air Quality API index to filter nearby places, ie.: if you are looking for parks in your area, you will show only parks with good air quality.
Use the Maps JavaScript API with the ImateMapType to display the individual tiles needed to cover the entire viewport of your Google map. Heatmap tiles will refresh as user engage with the map by panning, zooming or changing location.
Keep in mind the allowed zoom level value are up to 16. The Air Quality API heatmap tile layer might disappear at hyperlocal search.
You can select Heatmap map Types within a limited set of Air Quality Indexes:
UAQI_RED_GREEN - Universal Air Quality Index red-green palette.
UAQI_INDIGO_PERSIAN - Universal Air Quality Index indigo-persian palette.
PM25_INDIGO_PERSIAN - PM2.5 index indigo-persian palette.
GBR_DEFRA - Daily Air Quality Index (UK) color palette.
DEU_UBA - German Local Air Quality Index color palette.
CAN_EC - Canadian Air Quality Health Index color palette.
FRA_ATMO - France Air Quality Index color palette.
US_AQI - US Air Quality Index color palette.
Make sure you indicate the color scale for users to understand the value and its color ranking:
1 query every place (all on map load or only on user selection).
Heatmap tile layer: every tile image is 256*256px and to cover a standard map presented on a mobile device or web you need 12-14 tiles. Each tile pulled is counted as 1 SKU unit.
Nearby Search (New) API: 1 query every 20 places displayed. Different billing according to Place data that are part of the query response.
Conclusion
We showed that Air Quality API can be an important data point for users to decide on a place to visit. Therefore, the Air Quality data should be visible the earliest possible in the search experience with care to the amount of information displayed at once and how it is made visible.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eUse Air Quality API data to enhance place search experiences by providing real-time and historical air quality information globally and locally.\u003c/p\u003e\n"],["\u003cp\u003eDisplay air quality data early in the search experience on location pins using color codes and detailed information on selection, or as a heatmap layer for a broad overview.\u003c/p\u003e\n"],["\u003cp\u003eTailor the level of air quality information displayed to your users' needs, considering factors like AQI, pollutants, and health recommendations.\u003c/p\u003e\n"],["\u003cp\u003eBe mindful of API usage and costs associated with queries for location data, air quality data, and heatmap tiles.\u003c/p\u003e\n"],["\u003cp\u003eLeverage the Air Quality API to improve user experience by enabling informed decisions about places to visit based on air quality conditions.\u003c/p\u003e\n"]]],["The document explains how to integrate the Air Quality API into place search experiences. Key actions include: displaying real-time or historical air quality data (hourly for up to 30 days) on location pins using current conditions, or via a heatmap overlay, representing air quality conditions. Information presented includes Universal or Local Air Quality Indexes (AQI), color codes, pollutant levels, and health recommendations. It details how to use these elements and different visualization like heatmap tiles and individual value for location. It also explains query count and cost associated.\n"],null,["In this document, you will look into **how to use [Air Quality API](/maps/documentation/air-quality/overview) to build rich place search experiences.**\nWe will show how air quality can be a signal of value for users from the very beginning\nuntil the end of the funnel and how Air Quality API data can be embedded into existing experiences.\n\nUse Cases and added value\n\nAir Quality API signals can fit into various search experiences such as\nwhen users are looking for a location to visit. Air Quality API offers:\n\n- **Real time** \\* and historical data - fresh, accurate data that represents the current state as well as back in time data within a 30 days window in an hourly resolution. (\\* an hourly snapshot of outdoor air quality)\n- **Global and local data** - covering entire areas in 100+ countries yet highly localized (up to 500m) Air Quality API data provides key signals for users to compare and make decisions on the most appropriate place.\n\nAir quality can be drastically different even for near locations \n\nSample Walkthrough\n\nShow air quality data early in the experience\n\nThere are two main ways to show the Air Quality API data:\n\n- [Current conditions](/maps/documentation/air-quality/current-conditions) / [hourly](/maps/documentation/air-quality/history): get individual values to display against each location. \n\n (go to section: [Display Air Quality API data on location pins](/maps/architecture/air-quality-awareness-for-places#display_Air%20Quality_api_data_on_location_pins))\n\n- [Heatmap tiles](/maps/documentation/air-quality/heatmaps): overlay a a colored layer representing current outdoor air quality conditions on top of your map. Country specific layers indexes are available. \n\n (go to section: [Display Air Quality API heatmap layer on a map](/maps/architecture/air-quality-awareness-for-places#display_Air%20Quality_api_heatmap_layer_on_a_map))\n\nDisplay Air Quality API data on location pins\n\n- Choose your location index: Universal AQI or a Local AQI (up to 70 different [Air Quality Indexes (AQI)](/maps/documentation/air-quality/laqis) are available). An air quality index (AQI) is the scale by which a certain country, for example, the [U.S. EPA](https://www.epa.gov/), categorizes different air quality levels, based on different calculation methods, data sources, and designated purposes.\n- Start visualizing the main Air Quality API value and color code straight from the place search experience. \n\n\ndefault display could include the color code only. \n\nDisplay more [Air Quality API information](https://developers.google.com/maps/documentation/air-quality/response-data) on pin selection:\n\n\u003cbr /\u003e\n\n- Universal AQI / Local AQI meaning. \n- [Pollutant levels](/maps/documentation/air-quality/pollutants), which are a measure of particles and gasses in the air: Dominant pollutant, Concentration, Sources \\& Effects.\n- [Health recommendations](/maps/documentation/air-quality/health-recommendations), which are recommended actions for current air quality conditions.\n\n| **Tip:** leverage Advanced Markers to build custom markers and manage markers collision.\n\n- You can adjust the level of information displayed by default to serve your needs. Keep in mind that data points for a location are often useful in comparison to other locations.\n\n\nAir quality section display example \n\n\u003cbr /\u003e\n\nAir Quality Response \n\n```\n\n{\n \"dateTime\": \"2023-08-09T10:00:00Z\",\n \"regionCode\": \"fr\",\n \"indexes\": [\n {\n \"code\": \"uaqi\",\n \"displayName\": \"Universal AQI\",\n \"aqi\": 76,\n \"aqiDisplay\": \"76\",\n \"color\": {\n \"red\": 0.4117647,\n \"green\": 0.77254903,\n \"blue\": 0.20392157\n },\n \"category\": \"Good air quality\",\n \"dominantPollutant\": \"pm10\"\n },\n …\n ],\n \"pollutants\": [\n {\n \"code\": \"co\",\n \"displayName\": \"CO\",\n \"fullName\": \"Carbon monoxide\",\n \"concentration\": {\n \"value\": 95.18,\n \"units\": \"PARTS_PER_BILLION\"\n }...\n },\n …\n ],\n \"healthRecommendations\": -{\n \"generalPopulation\": \"With this level of air quality, you have no limitations. Enjoy the outdoors!\",\n \"elderly\": \"If you start to feel respiratory discomfort such as coughing or breathing difficulties, consider red ...\",\n \"lungDiseasePopulation\": …\n }\n}\n\n```\n\n- Alternatively, you can query Air Quality data only on interaction with a location.\n\n- You can use Air Quality API index to filter nearby places, ie.: if you are looking for parks in your area, you will show only parks with good air quality.\n\n| **Tip:** to use the color code from the Air Quality API response in JavaScript, you can convert the response as described below. The individual colors (red, green, blue, alpha) might not always be part of the response.\n\nAir Quality Response \n\n```c++\n...\n\"color\":{\n \"red\": 0.9490196,\n \"green\": 0.98039216,\n \"blue\": 0.019607844\n}\n...\n```\nConvert to RGB \n\n```gdscript\n var red = parseInt(colorResponse.red*255)|| 1;\n var green = parseInt(colorResponse.green*255)|| 1;\n var blue = parseInt(colorResponse.blue*255)|| 1; \n // --\u003e output rgb(241,250,5)\n```\n\nDisplay Air Quality API heatmap layer on a map\n\nHeatmap colored tiles are a great way:\n\n- to provide a large area overview.\n- to quickly show nuances within that area.\n\nUse the [Maps JavaScript API](/maps/documentation/javascript/usage-and-billing#pricing-for-product) with the [ImateMapType](/maps/documentation/javascript/maptypes#ImageMapTypes) to display the individual tiles needed to cover the entire viewport of your Google map. Heatmap tiles will refresh as user engage with the map by panning, zooming or changing location.\n\n| **Tip:** if you want to display the basemap points of interest and markers on top of the map, leverage **[GoogleMapsOverlay](https://deck.gl/docs/api-reference/google-maps/google-maps-overlay)** with **[deck.gl](https://deck.gl/docs/api-reference/google-maps/google-maps-overlay)** and create a new **[TileLayer](https://deck.gl/docs/api-reference/geo-layers/tile-layer)**.\n\nKeep in mind the allowed [zoom level](/maps/documentation/air-quality/heatmaps#about_the_heatmap_endpoint) value are up to 16. \nThe Air Quality API heatmap tile layer might disappear at hyperlocal search. \n\nYou can select [Heatmap map Types](/maps/documentation/air-quality/reference/rest/v1/mapTypes.heatmapTiles/lookupHeatmapTile#maptype) within a limited set of Air Quality Indexes:\n\n\u003cbr /\u003e\n\n\n- UAQI_RED_GREEN - Universal Air Quality Index red-green palette.\n- UAQI_INDIGO_PERSIAN - Universal Air Quality Index indigo-persian palette.\n- PM25_INDIGO_PERSIAN - PM2.5 index indigo-persian palette.\n- GBR_DEFRA - Daily Air Quality Index (UK) color palette.\n- DEU_UBA - German Local Air Quality Index color palette.\n- CAN_EC - Canadian Air Quality Health Index color palette.\n- FRA_ATMO - France Air Quality Index color palette.\n- US_AQI - US Air Quality Index color palette.\n\n- Make sure you indicate the color scale for users to understand the value and its color ranking:\n - gradient scale UAQI (0-100): Poor / Excellent\n- Color palette CSS code snippet: \n\n```c++\n.gradient-scale { \nbackground: linear-gradient(to right, \n rgb(99, 20, 161) 0%, /* purple */\n rgb(149, 0, 25) 20%, /* red */\n rgb(248, 47, 21) 40%, /* orange */\n rgb(255, 248, 35) 60%, /* yellow */\n rgb(34,163,120) 80%, /* steelblue */\n rgb(255,255,255) 100% /* white */\n );\n}\n```\n - solid colors to represent key point in UAQI (0-100) scale: Poor / Excellent\n\nQueries count and cost associated\n - [Maps JavaScript API](/maps/documentation/javascript/usage-and-billing#pricing-for-product): 1 map at load of the experience.\n - [Air Quality API](/documentation/air-quality/usage-and-billing):\n - 1 query every place (all on map load or only on user selection).\n - Heatmap tile layer: every tile image is 256\\*256px and to cover a standard map presented on a mobile device or web you need 12-14 tiles. Each tile pulled is counted as 1 SKU unit.\n - [Nearby Search (New) API](/maps/documentation/places/web-service/search-nearby-new): 1 query every 20 places displayed. Different billing according to [Place data](/maps/documentation/places/web-service/usage-and-billing#data-skus) that are part of the query response.\n\nConclusion\n- We showed that Air Quality API can be an important data point for users to decide on a place to visit. Therefore, the Air Quality data should be visible the earliest possible in the search experience with care to the amount of information displayed at once and how it is made visible. \n\nNext Actions\n- Suggested Further Reading:\n - [Improve local discovery with Nearby Search (New) API](/maps/architecture/improved-cost-effective-local-discovery)\n - [See your data in real time with Data-driven styling](/maps/architecture/dds-real-time)\n\nContributors\n- Google maintains this article. The following contributors originally wrote it. \n Principal author:\n- [Thomas Anglaret](https://www.linkedin.com/in/thomas-anglaret/) \\| Solutions Engineer"]]