با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
نقطه پایانی history اطلاعات ساعتی تاریخی کیفیت هوا را برای یک مکان خاص، برای یک محدوده زمانی معین، حداکثر تا 30 روز ارائه می دهد. می توانید AQI و اطلاعات مربوطه را که بازگردانده می شوند (مانند سطح غلظت آلاینده ها و توصیه های بهداشتی) کنترل کنید.
با ارسال یک درخواست HTTP POST می توانید تاریخچه کیفیت هوای ساعتی را با استفاده از نقطه پایانی history درخواست کنید:
گزینه های درخواست خود را در بدنه درخواست JSON قرار دهید. بدنه درخواست شامل مکان و محدوده زمانی است که می‌خواهید تاریخچه ساعتی کیفیت هوا را دریافت کنید. همچنین ممکن است شامل گزینه های مختلفی برای کنترل اطلاعات کیفیت هوا در پاسخ باشد.
APIs Explorer به شما امکان می دهد درخواست های زنده بنویسید تا بتوانید با API و گزینه های API آشنا شوید:
کد زیر نحوه ساخت بدنه درخواست برای یک درخواست تاریخچه یک ساعته را با استفاده از روش history نشان می دهد. در این مثال، مکان و زمان گذشته را تنظیم می کنید.
تماس بالا پاسخ JSON زیر را ایجاد می کند. برای جزئیات بیشتر درباره داده‌های پاسخ، به داده‌های پاسخ مراجعه کنید.
{"hoursInfo":[{"dateTime":"2023-06-26T15:00:00Z","indexes":[{"code":"uaqi","displayName":"Universal AQI","aqi":73,"aqiDisplay":"73","color":{"red":118,"green":202,"blue":51,"alpha":255},"category":"Good air quality","dominantPollutant":"pm10"}]}],"regionCode":"us"}
نمونه درخواست محدوده زمانی
درخواست محدوده زمانی
کد زیر نحوه ساخت بدنه درخواستی برای history ای را نشان می دهد که چندین رکورد از کیفیت هوای ساعتی تاریخی را برمی گرداند.
شما می توانید با تعیین یک بازه زمانی، به معنی مهر زمانی شروع و پایان، یا با تعیین تعداد ساعات برگشت از زمان فعلی، چندین رکورد را درخواست کنید.
در مثال زیر، چون اندازه صفحه را 2 تنظیم کرده اید، درخواست شما برای چهار ساعت سابقه کیفیت هوا در دو صفحه بازگردانده می شود که هر صفحه حاوی دو ساعت داده است.
تماس های بالا یک پاسخ JSON به شکل زیر ایجاد می کنند. برای جزئیات بیشتر درباره داده‌های پاسخ، به داده‌های پاسخ مراجعه کنید.
هر دو تماس فوق چهار ساعت داده کیفیت هوا را درخواست می کنند. با این حال، از آنجایی که ویژگی pageSize را در درخواست روی 2 تنظیم کرده اید، پاسخ فقط شامل نتایج دو ساعت اخیر می شود.
{"hoursInfo":[{"dateTime":"2023-06-15T11:00:00Z","indexes":[{"code":"uaqi","displayName":"Universal AQI","aqi":83,"aqiDisplay":"83","color":{"red":74,"green":185,"blue":54,"alpha":255},"category":"Excellent air quality","dominantPollutant":"o3"}]},{"dateTime":"2023-06-15T10:00:00Z","indexes":[{"code":"uaqi","displayName":"Universal AQI","aqi":89,"aqiDisplay":"89","color":{"red":48,"green":175,"blue":55,"alpha":255},"category":"Excellent air quality","dominantPollutant":"o3"}]}],"regionCode":"us","nextPageToken":"ChYaEgl3gv3XubVCQBEsNMY9TTdUMTE6MDA6MDA"}
توجه داشته باشید که پاسخ شامل ویژگی nextPageToken نیز می شود. از این ویژگی برای دسترسی به صفحه بعدی نتایج که حاوی داده های دو ساعت بعدی است استفاده کنید.
برای دسترسی به صفحه بعدی نتایج، یک درخواست دوم به نقطه پایانی history ارائه دهید، اما این بار ویژگی pageToken را با مقدار nextPageToken از اولین پاسخ تنظیم کنید.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThe \u003ccode\u003ehistory\u003c/code\u003e endpoint provides historical hourly air quality data for specific locations, covering up to 30 days.\u003c/p\u003e\n"],["\u003cp\u003eYou can request data for a single hour or a time range, controlling the air quality indexes and pollutants information returned.\u003c/p\u003e\n"],["\u003cp\u003eRequests are made via HTTP POST to the endpoint, including location and time parameters in the JSON request body.\u003c/p\u003e\n"],["\u003cp\u003eResponses include hourly air quality information with indexes, categories, and dominant pollutants, potentially paginated for larger requests.\u003c/p\u003e\n"],["\u003cp\u003eWhen requesting data for a time range, results are paginated, and you can retrieve subsequent pages using the \u003ccode\u003enextPageToken\u003c/code\u003e provided in the response.\u003c/p\u003e\n"]]],[],null,["The [`history`](/maps/documentation/air-quality/reference/rest/v1/history/lookup) endpoint provides\nhistorical hourly air quality information for a specific location, for a given\ntime range, up to a maximum of 30 days. You can control the which AQIs and\npertinent information are returned (such as pollutants concentration level and\nhealth recommendations).\n\nYou can request history of hourly air quality using the\n[`history`](/maps/documentation/air-quality/reference/rest/v1/history/lookup)\nendpoint by sending an HTTP POST request to: \n\n```html\nhttps://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY\n```\n\nInclude your request options in the JSON\n[request body](/maps/documentation/air-quality/reference/rest/v1/history/lookup#request-body). The request body\ncontains the location and the time range for which you would like to get the\nhourly air quality history. It may also include various options to control\nwhat air quality information to include in the response.\n\nThe APIs Explorer lets you make live requests so that you can get familiar with\nthe API and the API options: \n[Try it!](#try_it)\n\nExample of a single hour request\n\nSingle hour request body\n\nThe following code shows how to construct a request body for a single hour\nhistory request using the\n[`history`](/maps/documentation/air-quality/reference/rest/v1/history/lookup) method.\nIn this example, you set the location and the past timestamp.\n**Note:** Ensure that the `dateTime` parameter specifies a time period within the past 30 days. \n\n```json\ncurl -X POST -d '{\n \"dateTime\": \"2023-06-26T15:01:23Z\",\n \"location\": {\n \"latitude\": 37.419734,\n \"longitude\": -122.0827784\n }\n}' \\\n-H 'Content-Type: application/json' \\\n'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'\n```\n\nSingle hour response\n\nThe call above generates the following\n[JSON response](/maps/documentation/air-quality/reference/rest/v1/history/lookup#response-body).\nFor more details about the response data, see [Response data](/maps/documentation/air-quality/response-data).\n**Note:** By default, the response includes the Universal AQI with the basic AQI information. The AQI can be removed or replaced with a different AQI by setting the corresponding parameter(s). \n\n```json\n{\n \"hoursInfo\": [\n {\n \"dateTime\": \"2023-06-26T15:00:00Z\",\n \"indexes\": [\n {\n \"code\": \"uaqi\",\n \"displayName\": \"Universal AQI\",\n \"aqi\": 73,\n \"aqiDisplay\": \"73\",\n \"color\": {\n \"red\": 118,\n \"green\": 202,\n \"blue\": 51,\n \"alpha\": 255\n },\n \"category\": \"Good air quality\",\n \"dominantPollutant\": \"pm10\"\n }\n ]\n }\n ],\n \"regionCode\": \"us\"\n}\n```\n| **Note:** If a `color` field value is `0`, that field is omitted from the response.\n\nExample of time range request\n\nTime range request\n\nThe following code shows how to construct a request body for a\n[`history`](/maps/documentation/air-quality/reference/rest/v1/history/lookup) which returns multiple\nrecords of historical hourly air quality.\n\nYou can requesting multiple records by specifying a time range, meaning a start\nand end timestamp, or by specifying the number of hours back from the current\ntime.\n| **Note:** Results are returned in *pages* , with the most recent results returned in the first page. Use the `pageSize` property to control the maximum number of results per page. If more than one page is required to retrieve all results, then each page includes the `nextPageToken` property that contains the token you use to retrieve the subsequent page.\n\nIn the example below, because you set the page size to `2`, your request for\nfour hours of air quality history is returned in two pages, where each page\ncontains two hours of data. \n\n```json\ncurl -X POST -d '{\n \"hours\": 4,\n \"pageSize\": 2,\n \"pageToken\":\"\",\n \"location\": {\n \"latitude\": 37.419734,\n \"longitude\": -122.0827784\n }\n}' \\\n-H 'Content-Type: application/json' \\\n'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'\n```\n\nYou can make a similar request by passing the start and end timestamps:\n**Note:** Ensure that the `startTime` and `endTime` parameters specify a time period within the past 30 days. \n\n```json\ncurl -X POST -d '{\n \"period\": {\n \"startTime\":\"2023-06-15T08:00:00Z\",\n \"endTime\":\"2023-06-15T12:00:00Z\"\n },\n \"pageSize\": 2,\n \"pageToken\":\"\",\n \"location\": {\n \"latitude\": 37.419734,\n \"longitude\": -122.0827784\n }\n}' \\\n-H 'Content-Type: application/json' \\\n'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'\n```\n\nTime range response\n\nThe calls above generates a\n[JSON response](/maps/documentation/air-quality/reference/rest/v1/history/lookup#response-body) in the form\nbelow. For more details about the response data, see\n[Response data](/maps/documentation/air-quality/response-data).\n\nBoth calls above request four hours air quality data. However, because you set\nthe `pageSize` property to `2` in the request, the response only includes\nresults for the most recent two hours. \n\n```json\n{\n \"hoursInfo\": [\n {\n \"dateTime\": \"2023-06-15T11:00:00Z\",\n \"indexes\": [\n {\n \"code\": \"uaqi\",\n \"displayName\": \"Universal AQI\",\n \"aqi\": 83,\n \"aqiDisplay\": \"83\",\n \"color\": {\n \"red\": 74,\n \"green\": 185,\n \"blue\": 54,\n \"alpha\": 255\n },\n \"category\": \"Excellent air quality\",\n \"dominantPollutant\": \"o3\"\n }\n ]\n },\n {\n \"dateTime\": \"2023-06-15T10:00:00Z\",\n \"indexes\": [\n {\n \"code\": \"uaqi\",\n \"displayName\": \"Universal AQI\",\n \"aqi\": 89,\n \"aqiDisplay\": \"89\",\n \"color\": {\n \"red\": 48,\n \"green\": 175,\n \"blue\": 55,\n \"alpha\": 255\n },\n \"category\": \"Excellent air quality\",\n \"dominantPollutant\": \"o3\"\n }\n ]\n }\n ],\n \"regionCode\": \"us\",\n \"nextPageToken\": \"ChYaEgl3gv3XubVCQBEsNMY9TTdUMTE6MDA6MDA\"\n}\n```\n\nNotice that the response also includes the `nextPageToken` property. Use this\nproperty to access the next page of the results, which contains the next two\nhours of data.\n\nTo access the next page of results, make a second request to the\n`history` endpoint, but this time set the `pageToken` property to\nthe value of `nextPageToken` from the first response.\n**Note:** When passing the `pageToken` property to access subsequent data pages, all other request parameters must match the original call that provided the page token. \n\n```json\ncurl -X POST -d '{\n \"hours\": 4,\n \"pageSize\": 2,\n \"pageToken\":\"ChYaEgl3gv3XubVCQBEsNMY9TTdUMTE6MDA6MDA\",\n \"location\": {\n \"latitude\": 37.419734,\n \"longitude\": -122.0827784\n }\n}' \\\n-H 'Content-Type: application/json' \\\n'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'\n```\n\nTry it!\n\nThe APIs Explorer lets you make sample requests so\nthat you can get familiar with the API and the API options.\n\n1. Select the API icon api\n on the right side of the page.\n\n2. Optionally edit the request parameters.\n\n3. Select the **Execute** button. In the dialog, choose the account\n that you want to use to make the request.\n\n4. In the APIs Explorer panel, select the fullscreen icon\n fullscreen to expand the APIs Explorer window."]]
