Điểm cuối publicAlerts cung cấp thông tin chi tiết về các cảnh báo sự kiện thời tiết cụ thể do các cơ quan quốc gia và quốc tế có thẩm quyền đưa ra. Những cảnh báo này cung cấp thông tin quan trọng, có thể cứu mạng.
Điểm cuối này trả về các cảnh báo thời tiết xảy ra theo thời gian thực cho một vĩ độ và kinh độ nhất định. Sau đây là các sự kiện thời tiết được hỗ trợ:
- Lượng mưa: Mưa, tuyết, mưa đá, hạn hán và nhiều yếu tố khác
- Nhiệt độ khắc nghiệt: Lạnh, nóng, đóng băng, sương giá, nhiệt độ cảm nhận và độ ẩm
- Sự kiện gió và bão: Bão tuyết, bão, lốc xoáy, bão nhiệt đới, giông bão, v.v.
- Suy giảm tầm nhìn: Sương mù, bão bụi và gió tuyết
- Các mối nguy hiểm liên quan đến nước: Lũ lụt, sóng thần, bão dâng, hiểm hoạ ven biển và nhiều mối nguy hiểm khác
- Sự kiện địa vật lý và địa chất: Động đất, lở đất và hoạt động núi lửa
- Vụ hỏa hoạn: Cháy rừng, thời tiết có nguy cơ cháy và nhiều thông tin khác
Để xem danh sách đầy đủ các sự kiện thời tiết được hỗ trợ, hãy xem Các loại sự kiện thời tiết.
Cảnh báo có thể chứa hoặc không chứa nội dung mô tả bằng ngôn ngữ địa phương, tuỳ thuộc vào nội dung có sẵn trong nguồn dữ liệu. Do các hạn chế về nguồn dữ liệu, thông tin được phân phát nguyên trạng (nội dung thô). Để biết thêm thông tin về các nguồn cảnh báo thời tiết, hãy xem phần Nguồn dữ liệu.
API này trả về thông tin sau cho một cảnh báo thời tiết cụ thể:
- Loại sự kiện thời tiết liên quan đến cảnh báo
- Danh sách các khu vực bị ảnh hưởng cùng với toạ độ xác định ranh giới địa lý của những khu vực đó
- Tóm tắt sự kiện thời tiết trong một câu
- Mức độ nghiêm trọng, mức độ chắc chắn và mức độ khẩn cấp
- Nội dung mô tả về hướng dẫn hành động được đề xuất cho đối tượng mục tiêu
- Đề xuất về an toàn
- Thời gian bắt đầu và kết thúc của cảnh báo
- Tên và trang web của cơ quan xuất bản
API Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để có thể làm quen với API và các lựa chọn API:
Giới thiệu về yêu cầu cảnh báo thời tiết
Để yêu cầu thông tin cảnh báo thời tiết, hãy gửi một yêu cầu HTTP GET đến:
https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE&languageCode=LANGUAGE_CODE
Thêm toạ độ vĩ độ và kinh độ của vị trí vào các tham số URL yêu cầu của bạn.
Giới thiệu về câu trả lời cho cảnh báo thời tiết
Weather API trả về các trường sau trong phần nội dung phản hồi:
| Trường | Loại | Mô tả | Bắt buộc hoặc không bắt buộc |
|---|---|---|---|
alertId |
Chuỗi | Mã cảnh báo. Bạn cũng có thể tìm thấy thông tin này trên trang web của nhà cung cấp dữ liệu. | Bắt buộc |
alertTitle |
Chuỗi | Tiêu đề của cảnh báo, mô tả sự kiện thời tiết. Lưu ý: Đây là chuỗi duy nhất được dịch khi tham số mã ngôn ngữ được đưa vào yêu cầu. |
Bắt buộc |
eventType |
Enum | Loại sự kiện thời tiết liên quan đến cảnh báo. Để xem danh sách đầy đủ các sự kiện thời tiết được hỗ trợ, hãy xem Các loại sự kiện thời tiết. |
Bắt buộc |
areaName |
Chuỗi | Tên của khu vực địa lý chịu ảnh hưởng của cảnh báo, bao gồm cả vị trí được yêu cầu. | Bắt buộc |
polygon |
Chuỗi | Toạ độ xác định một vùng có kích thước khép kín của cảnh báo. | Không bắt buộc |
description |
Chuỗi | Một cụm từ ngắn gọn tóm tắt nội dung mô tả sự kiện bằng ngôn ngữ đã chỉ định (ví dụ: "Cảnh báo lốc xoáy"). | Không bắt buộc |
severity |
Enum | Mức độ nghiêm trọng của cảnh báo:
|
Không bắt buộc |
certainty |
Enum | Mức độ chắc chắn của cảnh báo:
|
Không bắt buộc |
urgency |
Enum | Mức độ khẩn cấp của cảnh báo:
|
Không bắt buộc |
instruction |
Chuỗi | Nội dung mô tả về hướng dẫn hành động thích ứng cho đối tượng mục tiêu. | Không bắt buộc |
safetyRecommendations |
Chuỗi | Đề xuất an toàn dựa trên mã của cơ quan công quyền. Bao gồm các chỉ thị cấp cao nhất và phụ đề có thông tin bổ sung. | Không bắt buộc |
timezoneOffset |
Chuỗi | Mức chênh lệch múi giờ của sự kiện, ở định dạng +/-HH:MM. | Bắt buộc |
startTime |
DateTime | Ngày và giờ Epoch có hiệu lực (giờ UTC) của thông tin trong thông báo cảnh báo. | Không bắt buộc |
expirationTime |
DateTime | Ngày và giờ theo Epoch (giờ UTC) mà một cảnh báo dự kiến sẽ kết thúc. Giá trị này có thể là giá trị rỗng đối với các sự kiện kéo dài vô thời hạn. Trong trường hợp đó, tiêu đề sẽ cho biết sự kiện "đang diễn ra". | Không bắt buộc |
dataSource |
Enum | Thông tin về cơ quan, bao gồm nhà xuất bản, tên và URL. | Bắt buộc |
regionCode |
Enum | Mã khu vực của vị trí đã được yêu cầu. | Không bắt buộc |
Nguồn dữ liệu
Điểm cuối cảnh báo thời tiết trả về dữ liệu do các nhà cung cấp được liệt kê trong bảng sau đây xuất bản. Dựa trên toạ độ vĩ độ và kinh độ được cung cấp trong yêu cầu, phần nội dung phản hồi sẽ hiển thị dữ liệu từ cơ quan địa phương thích hợp.
Các nhà cung cấp có trong nguồn cấp dữ liệu tuân thủ Nguyên tắc về Cảnh báo công khai của Google. Google có thể cập nhật danh sách nhà cung cấp bất cứ lúc nào.
Phân bổ
Trên tất cả những màn hình hiển thị dữ liệu, ứng dụng khách hàng phải có thông tin phân bổ cho nguồn ban đầu bằng cách sử dụng trường dataSource:
"dataSource": {
"publisher": "NOAA",
"name": "National Weather Service",
"authorityUri": "https://www.weather.gov/"
}
Thông tin ghi nhận quyền tác giả phải bao gồm tên đầy đủ của nguồn dữ liệu (như được cung cấp trong trường name) và siêu liên kết đến nguồn dữ liệu bằng URL được cung cấp trong trường authorityUri (ví dụ: "Cục Thời tiết Quốc gia").
Loại sự kiện thời tiết
Sau đây là các loại sự kiện thời tiết được hỗ trợ:
| Loại sự kiện thời tiết | |
|---|---|
ACID_RAINAVALANCHEBLIZZARDBLOWING_SNOWCOASTAL_FLOODCOASTAL_HAZARDCOLDCYCLONEDROUGHTEXTRATROPICAL_CYCLONEFIRE_WEATHERFLASH_FLOODFLOODFOGFREEZINGFREEZING_AIR_TEMPERATUREFREEZING_DRIZZLEFREEZING_RAINFROSTGALEGLAZEHAILHAZARDOUS_SEASHEATHUMIDITYHURRICANEICE_STORMLAKE_EFFECT_SNOWMONSOONMUDDY_FLOODOUTFLOWRAIN
|
RIVER_FLOODINGSEVERE_THUNDERSTORM_WARNINGSNOWSNOWSQUALLSTORMSTORM_SURGETHUNDERTHUNDERSTORMTORNADOTORNADO_WARNINGTROPICAL_CYCLONETROPICAL_CYCLONE_WARNINGS_AND_WATCHESTROPICAL_DISTURBANCETROPICAL_STORMTYPHOONWINDWIND_CHILLWIND_WAVEWINTER_STORMWILDFIREBUSHFIREFIRELANDSLIDEEARTHQUAKEDUST_STORMAFTERSHOCKTSUNAMIVOLCANIC_ASHVOLCANIC_ERUPTIONRADIATION |
Hành vi dịch câu trả lời
Google chỉ cung cấp bản dịch cho trường alertTitle. Các trường khác như eventType, areaName, instruction và safetyRecommendations cũng có thể được dịch, tuỳ thuộc vào khả năng hỗ trợ ngôn ngữ của nguồn dữ liệu ban đầu; tuy nhiên, Google không thể cung cấp bản dịch độc lập cho các trường này.
Dựa trên tham số languageCode có trong yêu cầu, trường alertTitle dự kiến sẽ có những hành vi sau:
languageCodeđược hỗ trợ: NếulanguageCodeđược yêu cầu vừa được cung cấp vừa được hỗ trợ, thì phản hồi sẽ được trả về bằng ngôn ngữ được yêu cầu.- Không được hỗ trợ
languageCode: Trong trường hợplanguageCodeđược yêu cầu không được hỗ trợ và không tìm thấy lựa chọn thay thế tương tự, điểm cuối sẽ trả về phản hồi bằng tiếng Anh theo mặc định. - Không cung cấp
languageCode: Theo mặc định, điểm cuối sẽ trả về phản hồi bằng tiếng Anh.
Ví dụ về yêu cầu cảnh báo thời tiết
Ví dụ sau đây yêu cầu thông tin về cảnh báo thời tiết cho một thị trấn ở Bắc Carolina:
curl -X GET "https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=35.824635 &location.longitude=-78.3168047 &languageCode=en"
Nội dung phản hồi như sau:
{ "weatherAlerts": [ { "alertId": "urn:oid:2.49.0.1.840.0.2416b1b5a6f51d29ef4b94948328dca303fbbb5c.001.1", "alertTitle": { "text": "Flash Flood Warning", "languageCode": "en" }, "eventType": "FLASH_FLOOD", "areaName": "Franklin, NC; Johnston, NC; Nash, NC; Wake, NC", "polygon": "{\"type\":\"Polygon\",\"coordinates\":[[[-78.450000,35.820000],[-78.410000,35.730000],[-78.280000,35.660000],[-78.180000,35.740000],[-77.840000,36.150000],[-77.890000,36.140000],[-77.900000,36.160000],[-77.920000,36.170000], [-77.930000,36.190000], [-77.940000,36.190000],[-77.950000,36.180000],[-77.970000,36.190000],[-77.970000,36.180000], [-77.980000,36.180000],[-78.010000,36.210000],[-78.040000,36.210000],[-78.110000,36.210000],[-78.130000,36.230000], [-78.350000,35.940000],[-78.450000,35.820000]]]}", "description": "FFWRAH\n\nThe National Weather Service in Raleigh has issued a\n\n* Flash Flood Warning for... \nEastern Franklin County in central North Carolina...\nNorth Central Johnston County in central North Carolina... \nWestern Nash County in central North Carolina...\nEast Central Wake County in central North Carolina... \n\n* Until 530 PM EDT.\n\n* At 224 PM EDT, local law enforcement reported flash flooding in\nSpring Hope. Between 3 and 5 inches of rain have fallen. \nAdditional rainfall amounts of 1 to 3 inches are possible in the\nwarned area.\n\nHAZARD...Life threatening flash flooding. Heavy rain producing\nflash flooding.\n\nSOURCE...Law enforcement reported.\n\nIMPACT...Life threatening flash flooding of creeks and streams,\nurban areas, highways, streets and underpasses.\n\n* Some locations that will experience flash flooding include... \nZebulon, Bunn, Wendell, Spring Hope, Middlesex, Castalia,\nCenterville, Pilot, Emit and Aventon.", "severity": "SEVERE", "certainty": "LIKELY", "urgency": "IMMEDIATE", "instruction": [ "Turn around, don't drown when encountering flooded roads. Most flood\ndeaths occur in vehicles." ], "safetyRecommendations": [ { "directive": "Build an emergency kit and make a family communications plan.", "subtext": "Follow the instructions at http://www.ready.gov/build-a-kit for building an emergency kit and http://www.ready.gov/make-a-plan for a family communications plan." }, { "directive": "Be aware that flash flooding can occur. ", "subtext": "If there is any possibility of a flash flood, move immediately to higher ground. Do not wait for instructions to move." }, ... ], "timezoneOffset": "-14400s", "startTime": "2025-08-06T18:24:00Z", "expirationTime": "2025-08-06T21:30:00Z", "dataSource": { "publisher": "NOAA", "name": "National Weather Service", "authorityUri": "https://www.weather.gov/" } } ], "regionCode": "US" }
Hãy dùng thử!
Trình khám phá API cho phép bạn đưa ra các yêu cầu mẫu để có thể làm quen với API và các lựa chọn API.
Chọn biểu tượng API api ở bên phải trang.
Bạn có thể chỉnh sửa các tham số yêu cầu (không bắt buộc).
Chọn nút 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.
Trong bảng điều khiển APIs Explorer, hãy chọn biểu tượng toàn màn hình fullscreen (toàn màn hình) để mở rộng cửa sổ APIs Explorer.