L'endpoint
publicAlerts
fornisce i dettagli per avvisi di eventi meteorologici specifici emessi da
agenzie nazionali e internazionali autorevoli. Questi avvisi forniscono informazioni cruciali
che potrebbero salvare vite umane.
L'endpoint restituisce allerte meteo che si verificano in tempo reale per una determinata latitudine e longitudine. Gli eventi meteo supportati includono:
- Precipitazioni:pioggia, neve, grandine, siccità e altro ancora
- Temperature estreme:freddo, caldo, gelo, brina, raffreddamento e umidità
- Eventi di vento e tempesta:bufere di neve, uragani, tornado, tempeste tropicali, temporali e altro ancora
- Problemi di visibilità:nebbia, tempeste di polvere e raffiche di neve
- Pericoli legati all'acqua:inondazioni, tsunami, mareggiate, pericoli in aree costiere e altro ancora
- Eventi geofisici e geologici:terremoti, frane e attività vulcanica
- Incendi:incendi boschivi, condizioni meteorologiche favorevoli agli incendi e altro ancora
Per un elenco completo degli eventi meteo supportati, consulta Tipi di eventi meteo.
Gli avvisi possono contenere o meno descrizioni localizzate, a seconda di ciò che è disponibile nell'origine dati. A causa delle limitazioni dell'origine dati, le informazioni vengono pubblicate così come sono (contenuti non elaborati). Per ulteriori informazioni sulle fonti degli avvisi meteo, consulta Origini dati.
L'API restituisce le seguenti informazioni per un determinato avviso meteo:
- Il tipo di evento meteorologico associato all'avviso
- Un elenco delle aree interessate insieme alle coordinate che definiscono i confini geografici di queste aree
- Un riepilogo dell'evento meteo in una frase
- Livelli di gravità, certezza e urgenza
- Una descrizione delle istruzioni per i consigli sulle azioni per il pubblico di destinazione
- Consigli per la sicurezza
- Ora di inizio e di fine dell'avviso
- Il nome e il sito web dell'autorità di pubblicazione
L'API Explorer ti consente di effettuare richieste in tempo reale per familiarizzare con l'API e le relative opzioni:
Informazioni sulle richieste di allerte meteo
Per richiedere informazioni sugli avvisi meteo, invia una richiesta HTTP GET a:
https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE&languageCode=LANGUAGE_CODE
Includi le coordinate di latitudine e longitudine della posizione nei parametri dell'URL della richiesta.
Informazioni sulle risposte alle allerte meteo
L'API Weather restituisce i seguenti campi nel corpo della risposta:
| Campo | Tipo | Descrizione | Obbligatorio o facoltativo |
|---|---|---|---|
alertId |
Stringa | L'ID dell'avviso. Queste informazioni sono disponibili anche sul sito web del fornitore di dati. | Obbligatorio |
alertTitle |
Stringa | Il titolo dell'avviso, che descrive l'evento meteorologico. Nota:questa è l'unica stringa che viene tradotta quando nella richiesta è incluso un parametro del codice lingua. |
Obbligatorio |
eventType |
Enum | Il tipo di evento meteorologico associato all'avviso. Per un elenco completo degli eventi meteorologici supportati, vedi Tipi di eventi meteorologici. |
Obbligatorio |
areaName |
Stringa | Il nome dell'area geografica interessata dall'avviso, che include la località richiesta. | Obbligatorio |
polygon |
Stringa | Coordinate che definiscono un'area dimensionale chiusa dell'avviso. | Facoltativo |
description |
Stringa | Una breve frase che riassume la descrizione dell'evento nella lingua specificata (ad esempio, "Allerta tornado"). | Facoltativo |
severity |
Enum | Il livello di gravità dell'avviso:
|
Facoltativo |
certainty |
Enum | Il livello di certezza dell'avviso:
|
Facoltativo |
urgency |
Enum | Il livello di urgenza dell'avviso:
|
Facoltativo |
instruction |
Stringa | Descrizione delle istruzioni per le azioni adattabili per il pubblico di destinazione. | Facoltativo |
safetyRecommendations |
Stringa | Consigli di sicurezza basati sui codici delle autorità pubbliche. Include direttive di primo livello e sottotitoli con informazioni aggiuntive. | Facoltativo |
timezoneOffset |
Stringa | L'offset del fuso orario dell'evento, nel formato +/-HH:MM. | Obbligatorio |
startTime |
DateTime | Data e ora Epoch effettive (ora UTC) delle informazioni nel messaggio di avviso. | Facoltativo |
expirationTime |
DateTime | La data e l'ora Epoch (ora UTC) in cui è previsto che un avviso termini. Potrebbe essere null per gli eventi di durata indefinita, nel qual caso il titolo indicherà che l'evento è "in vigore". | Facoltativo |
dataSource |
Enum | Dettagli dell'autorità, tra cui editore, nome e URL. | Obbligatorio |
regionCode |
Enum | Codice regione della località richiesta. | Facoltativo |
Origini dati
L'endpoint Avvisi meteo restituisce i dati pubblicati dai fornitori elencati nella tabella seguente. In base alle coordinate di latitudine e longitudine fornite nella richiesta, il corpo della risposta mostra i dati dell'autorità locale appropriata.
I fornitori inclusi nel feed seguono le linee guida per gli avvisi pubblici di Google. Google può aggiornare l'elenco dei fornitori in qualsiasi momento.
Attribuzione
In tutti i display in cui vengono presentati i dati, l'applicazione del cliente deve
includere un'attribuzione all'origine originale utilizzando il campo dataSource:
"dataSource": {
"publisher": "NOAA",
"name": "National Weather Service",
"authorityUri": "https://www.weather.gov/"
}
L'attribuzione deve includere il nome completo dell'origine dati (come fornito nel
campo name) e il link ipertestuale all'origine dati utilizzando l'URL fornito nel
campo authorityUri (ad esempio, "National Weather
Service").
Tipi di eventi meteorologici
Sono supportati i seguenti tipi di eventi meteo:
| Tipi di eventi meteorologici | |
|---|---|
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 |
Comportamento di traduzione delle risposte
Google fornisce traduzioni solo per il campo alertTitle. Anche altri campi, come eventType, areaName, instruction e safetyRecommendations, possono essere tradotti, a seconda del supporto linguistico dell'origine dati originale. Tuttavia, Google non può fornire traduzioni indipendenti per questi campi.
In base al parametro languageCode incluso nella richiesta, per il campo alertTitle sono previsti i seguenti comportamenti:
languageCodesupportato:se illanguageCoderichiesto è sia fornito che supportato, la risposta viene restituita nella lingua richiesta.languageCodenon supportato:nei casi in cui illanguageCoderichiesto non è supportato e non è possibile trovare un'alternativa simile, l'endpoint restituisce la risposta in inglese per impostazione predefinita.- Nessun
languageCodefornito: l'endpoint restituisce la risposta in inglese per impostazione predefinita.
Esempio di richiesta di allerta meteo
Il seguente esempio richiede informazioni sugli avvisi meteo per una città della Carolina del Nord:
curl -X GET "https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=35.824635 &location.longitude=-78.3168047 &languageCode=en"
Il corpo della risposta è il seguente:
{ "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" }
Prova
L'Explorer API ti consente di effettuare richieste di esempio per familiarizzare con l'API e le relative opzioni.
Seleziona l'icona API api sul lato destro della pagina.
(Facoltativo) Modifica i parametri di richiesta.
Seleziona il pulsante Esegui. Nella finestra di dialogo, scegli l'account che vuoi utilizzare per effettuare la richiesta.
Nel riquadro Explorer API, seleziona l'icona a schermo intero fullscreen per espandere la finestra di Explorer API.