تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تقدّم نقطة النهاية history معلومات تاريخية عن جودة الهواء كل ساعة لموقع جغرافي محدّد، وذلك لنطاق زمني معيّن، ولمدة تصل إلى 30 يومًا كحد أقصى. يمكنك التحكّم في مؤشرات جودة الهواء والمعلومات ذات الصلة التي يتم عرضها (مثل مستوى تركيز الملوّثات والتوصيات الصحية).
يمكنك طلب سجلّ بجودة الهواء كل ساعة باستخدام نقطة النهاية
history
من خلال إرسال طلب HTTP POST إلى:
أدرِج خيارات الطلب في نص الطلب بتنسيق JSON. يتضمّن نص الطلب الموقع الجغرافي والنطاق الزمني الذي تريد الحصول على سجلّ جودة الهواء بالساعة خلاله. وقد يتضمّن أيضًا خيارات متعدّدة للتحكّم في المعلومات المتعلقة بجودة الهواء التي سيتم تضمينها في الردّ.
يتيح لك "مستكشف واجهات برمجة التطبيقات" إرسال طلبات مباشرة لتتعرّف على واجهة برمجة التطبيقات وخياراتها:
يوضّح الرمز البرمجي التالي كيفية إنشاء نص طلب للحصول على بيانات سجلّ ساعة واحدة باستخدام طريقة 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-31 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
