Lịch sử

Điểm cuối history cung cấp thông tin về chất lượng không khí theo giờ trong quá khứ cho một vị trí cụ thể, trong một phạm vi thời gian nhất định, tối đa là 30 ngày. Bạn có thể kiểm soát AQI và thông tin liên quan được trả về (chẳng hạn như nồng độ chất ô nhiễm và các đề xuất về sức khoẻ).

Bạn có thể yêu cầu nhật ký chất lượng không khí theo giờ bằng history điểm cuối bằng cách gửi yêu cầu HTTP POST đến:

https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY

Đưa các tuỳ chọn yêu cầu vào nội dung yêu cầu JSON request body. Nội dung yêu cầu chứa vị trí và phạm vi thời gian mà bạn muốn lấy nhật ký chất lượng không khí theo giờ. Nội dung này cũng có thể bao gồm nhiều tuỳ chọn để kiểm soát thông tin về chất lượng không khí cần đưa vào phản hồi.

APIs Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để làm quen với API và các tuỳ chọn API:

Hãy làm thử!

Ví dụ về yêu cầu một giờ

Nội dung yêu cầu một giờ

Mã sau đây cho biết cách tạo nội dung yêu cầu cho yêu cầu nhật ký một giờ bằng phương thức history. Trong ví dụ này, bạn sẽ đặt vị trí và dấu thời gian trong quá khứ.

Lưu ý: Đảm bảo rằng tham số dateTime chỉ định một khoảng thời gian trong vòng 30 ngày qua.

curl -X POST -d '{
  "dateTime": "2023-06-26T15:01:23Z",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Phản hồi một giờ

Lệnh gọi ở trên tạo ra phản hồi JSON sau đây JSON response. Để biết thêm thông tin chi tiết về dữ liệu phản hồi, hãy xem bài viết Dữ liệu phản hồi.

Lưu ý: Theo mặc định, phản hồi bao gồm AQI toàn cầu với thông tin AQI cơ bản. Bạn có thể xoá hoặc thay thế AQI bằng một AQI khác bằng cách đặt(các) tham số tương ứng.

{
    "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"
}

Lưu ý: Nếu giá trị trường color là 0, thì trường đó sẽ bị bỏ qua trong phản hồi.

Ví dụ về yêu cầu phạm vi thời gian

Yêu cầu phạm vi thời gian

Mã sau đây cho biết cách tạo nội dung yêu cầu cho a history trả về nhiều bản ghi về chất lượng không khí theo giờ trong quá khứ.

Bạn có thể yêu cầu nhiều bản ghi bằng cách chỉ định một phạm vi thời gian (nghĩa là dấu thời gian bắt đầu và kết thúc) hoặc bằng cách chỉ định số giờ kể từ thời gian hiện tại.

Lưu ý: Kết quả được trả về theo trang, với kết quả gần đây nhất được trả về ở trang đầu tiên. Sử dụng thuộc tính pageSize để kiểm soát số lượng kết quả tối đa trên mỗi trang. Nếu cần nhiều hơn một trang để truy xuất tất cả kết quả, thì mỗi trang sẽ bao gồm thuộc tính nextPageToken chứa mã thông báo mà bạn dùng để truy xuất trang tiếp theo.

Trong ví dụ bên dưới, vì bạn đặt kích thước trang thành 2, nên yêu cầu của bạn về nhật ký chất lượng không khí trong 4 giờ sẽ được trả về trên 2 trang, trong đó mỗi trang chứa dữ liệu trong 2 giờ.

curl -X POST -d '{
  "hours": 4,
  "pageSize": 2,
  "pageToken":"",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Bạn có thể đưa ra yêu cầu tương tự bằng cách truyền dấu thời gian bắt đầu và kết thúc:

Lưu ý: Đảm bảo rằng tham số startTime và endTime chỉ định một khoảng thời gian trong vòng 30 ngày qua.

curl -X POST -d '{
  "period": {
      "startTime":"2023-06-15T08:00:00Z",
      "endTime":"2023-06-15T12:00:00Z"
  },
  "pageSize": 2,
  "pageToken":"",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Phản hồi phạm vi thời gian

Các lệnh gọi ở trên tạo ra phản hồi JSON ở dạng bên dưới. Để biết thêm thông tin chi tiết về dữ liệu phản hồi, hãy xem Dữ liệu phản hồi.

Cả hai lệnh gọi ở trên đều yêu cầu dữ liệu về chất lượng không khí trong 4 giờ. Tuy nhiên, vì bạn đặt thuộc tính pageSize thành 2 trong yêu cầu, nên phản hồi chỉ bao gồm kết quả cho 2 giờ gần đây nhất.

{
    "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"
}

Xin lưu ý rằng phản hồi cũng bao gồm thuộc tính nextPageToken. Sử dụng thuộc tính này để truy cập vào trang kết quả tiếp theo, chứa dữ liệu trong 2 giờ tiếp theo.

Để truy cập vào trang kết quả tiếp theo, hãy đưa ra yêu cầu thứ hai đến điểm cuối history, nhưng lần này hãy đặt thuộc tính pageToken thành giá trị của nextPageToken từ phản hồi đầu tiên.

**Lưu ý:** Khi truyền thuộc tính pageToken để truy cập vào các trang dữ liệu tiếp theo, tất cả các tham số yêu cầu khác phải khớp với lệnh gọi ban đầu đã cung cấp mã thông báo trang.

curl -X POST -d '{
  "hours": 4,
  "pageSize": 2,
  "pageToken":"ChYaEgl3gv3XubVCQBEsNMY9TTdUMTE6MDA6MDA",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Hãy làm thử!

APIs Explorer cho phép bạn đưa ra các yêu cầu mẫu để làm quen với API và các tuỳ chọn API.

1. Chọn biểu tượng API api ở bên phải trang.

2. Bạn có thể chỉnh sửa các tham số yêu cầu.

3. Chọn nút Execute (Thực thi). Trong hộp thoại, hãy chọn tài khoản mà bạn muốn dùng để đưa ra yêu cầu.

4. Trong bảng điều khiển APIs Explorer, hãy chọn biểu tượng toàn màn hình fullscreen để mở rộng cửa sổ APIs Explorer.