Weather - Get Weather Along Route

Umożliwia korzystanie z dokładnej lokalizacji, up-tominutowej prognozy, która zawiera oceny zagrożeń pogodowych i powiadomienia na trasie.
Interfejs Get Weather Along Route API to żądanie HTTP GET , które zwraca hiperlokalne (jeden kilometr lub mniej), up-to-the-minute prognozy pogody, oceny zagrożeń pogodowych i powiadomienia wzdłuż trasy opisanej jako sekwencja punktów trasy. Obejmuje to listę zagrożeń pogodowych wpływających na punkt trasy lub trasę, a zagregowany indeks zagrożeń dla każdego punktu trasy może być używany do malowania każdej części trasy zgodnie z tym, jak bezpieczna jest dla kierowcy. Podczas przesyłania punktów trasy zaleca się pozostanie w obrębie lub w pobliżu odległości, którą można pokonać w ciągu 120 minut lub krótko po niej. Dane są aktualizowane co pięć minut.

Usługa uzupełnia Azure Maps Route Service który pozwala najpierw zażądać trasy między początkiem a celem i użyć jej jako wejścia do punktu końcowego Weather Along Route.

Ponadto usługa obsługuje scenariusze generowania powiadomień pogodowych dla punktów trasy, w których występuje wzrost intensywności zagrożenia pogodowego. Na przykład, jeśli oczekuje się, że pojazd zacznie doświadczać ulewnego deszczu po dotarciu do punktu trasy, powiadomienie pogodowe o ulewnym deszczu zostanie wygenerowane dla tego punktu trasy, dzięki czemu produkt końcowy wyświetli powiadomienie o ulewnym deszczu, zanim kierowca dotrze do tego punktu trasy. Wyzwalacz określający, kiedy wyświetlić powiadomienie dla punktu trasy, może być oparty na przykład na geofencingu lub możliwej do wybrania odległości do punktu trasy.

API obejmuje wszystkie regiony planety z wyjątkiem szerokości geograficznych powyżej Grenlandii i Antarktydy.

GET {endpoint}/weather/route/json?api-version=1.1&query={query}

GET {endpoint}/weather/route/json?api-version=1.1&query={query}&language={language}

Parametry identyfikatora URI

Nagłówek żądania

Odpowiedzi

Zabezpieczenia

AadToken

Są to przepływy Microsoft Entra OAuth 2.0. W połączeniu z Azure zarządzaniem dostępem opartym na rolach może być używany do kontroli dostępu do Azure Maps API REST. Kontrola dostępu oparta na rolach Azure służy do wyznaczania dostępu do jednego lub więcej kont zasobów lub podzasobów Azure Maps. Każdy użytkownik, grupa lub jednostka usługi mogą mieć dostęp za pośrednictwem wbudowanej roli lub roli niestandardowej składającej się z co najmniej jednego uprawnienia do interfejsów API REST usługi Azure Maps.

Aby zaimplementować scenariusze, zalecamy wyświetlenie koncepcji uwierzytelniania . Podsumowując, ta definicja zabezpieczeń zawiera rozwiązanie do modelowania aplikacji za pośrednictwem obiektów, które mogą kontrolować dostęp do określonych interfejsów API i zakresów.

Typ: oauth2
Flow: implicit
Adres URL autoryzacji: https://login.microsoftonline.com/common/oauth2/authorize

Zakresy

subscription-key

Jest to klucz wspólny aprowizowany podczas tworzenie konta usługi Azure Maps w witrynie Azure Portal lub przy użyciu programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsu API REST.

Za pomocą tego klucza każda aplikacja może uzyskiwać dostęp do całego interfejsu API REST. Innymi słowy, ten klucz może służyć jako klucz główny na koncie, w którym są wystawiane.

W przypadku publicznie uwidocznionych aplikacji zalecamy użycie poufnych aplikacji klienckich podejście do uzyskiwania dostępu do interfejsów API REST usługi Azure Maps, aby klucz mógł być bezpiecznie przechowywany.

Typ: apiKey
W: header

SAS Token

Jest to token sygnatury dostępu współdzielonego tworzony na podstawie operacji List SAS na zasobie usługi Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.

Dzięki temu tokenowi każda aplikacja jest autoryzowana do uzyskiwania dostępu za pomocą kontroli dostępu opartej na rolach platformy Azure i szczegółowej kontroli wygaśnięcia, szybkości i regionów użycia dla określonego tokenu. Innymi słowy, token SAS może służyć do umożliwienia aplikacjom kontrolowania dostępu w sposób bardziej zabezpieczony niż klucz wspólny.

W przypadku publicznie uwidocznionych aplikacji zalecamy skonfigurowanie określonej listy dozwolonych źródeł w zasobie Mapowanie konta w celu ograniczenia nadużyć renderowania i regularnego odnawiania tokenu SAS.

Typ: apiKey
W: header

Przykłady

Successfully retrieve detailed weather casts along a route described as a sequence of waypoints

GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query=38.907,-77.037,0:38.907,-77.009,10:38.926,-76.928,20:39.033,-76.852,30:39.168,-76.732,40:39.269,-76.634,50:39.287,-76.612,60

{
  "summary": {
    "hazards": {
      "maxHazardIndex": 0
    },
    "iconCode": 35
  },
  "waypoints": [
    {
      "cloudCover": 70,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 38,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Mostly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 90,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 3.4
      },
      "wind": {
        "direction": {
          "degrees": 142
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 3
        }
      }
    },
    {
      "cloudCover": 65,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 38,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Mostly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 77,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 3.4
      },
      "wind": {
        "direction": {
          "degrees": 166
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 1
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      }
    },
    {
      "cloudCover": 43,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 35,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Partly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 44,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 3.2
      },
      "wind": {
        "direction": {
          "degrees": 163
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      }
    },
    {
      "cloudCover": 34,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 35,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Partly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 32,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 1.6
      },
      "wind": {
        "direction": {
          "degrees": 189
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 2
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 4
        }
      }
    },
    {
      "cloudCover": 54,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 38,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Mostly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 36,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 0.5
      },
      "wind": {
        "direction": {
          "degrees": 202
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 4
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 5
        }
      }
    },
    {
      "cloudCover": 46,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 35,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Partly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 38,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 2.4
      },
      "wind": {
        "direction": {
          "degrees": 222
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 4
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 5
        }
      }
    },
    {
      "cloudCover": 39,
      "hazards": {
        "maxHazardIndex": 0
      },
      "iconCode": 35,
      "isDayTime": false,
      "lightningCount": 0,
      "notifications": [],
      "precipitation": {
        "type": "SNOW",
        "dbz": 0
      },
      "shortPhrase": "Partly cloudy",
      "sunGlare": {
        "calculatedVehicleHeading": 43,
        "glareIndex": 0
      },
      "temperature": {
        "unit": "C",
        "unitType": 17,
        "value": 2.3
      },
      "wind": {
        "direction": {
          "degrees": 231
        },
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 4
        }
      },
      "windGust": {
        "speed": {
          "unit": "km/h",
          "unitType": 7,
          "value": 5
        }
      }
    }
  ]
}

Definicje

ErrorAdditionalInfo

Dodatkowe informacje o błędzie zarządzania zasobami.

ErrorDetail

Szczegóły błędu.

ErrorResponse

Wspólna odpowiedź na błędy dla wszystkich API Azure Resource Manager zwraca szczegóły błędów dla nieudanych operacji. (Jest to również zgodne z formatem odpowiedzi na błąd OData).

HazardDetail

Jeden wpis opisuje WeatherHazards.hazardDetails pojedyncze zagrożenie pogodowe w danym miejscu (poziom trasy, gdy jest przenoszony , WeatherAlongRouteSummary.hazardslub na każdy punkt przejazdowy, gdy jest przenoszony WaypointForecast.hazards). Łączy identyfikację hazardCode konkretnego typu zagrożenia, ocenę hazardIndex jego indywidualnej powagi w skali 0-4 oraz odpowiednią shortPhrase do wyświetlania w interfejsie użytkownika.

HazardIndex

Zagregowany wskaźnik nasilenia/zagrożenia dla każdego punktu można wykorzystać do kolorowego kodowania odcinków trasy, wskazując poziom bezpieczeństwa kierowców.

• 0: Brak zagrożenia
• 1: Bądź poinformowany, bądź świadomy
• 2: Uważaj, bądź przygotowany
• 3: Działaj
• 4: Zagrażająca życiu, nagły stan

IconCode

Numeryczny kod warunków pogodowych, który identyfikuje, którą ikonę wyświetlić na ekranie. Każda wartość w tej enumeracji odpowiada ikonie pogody w Azure Maps (np. Słoneczne, Pochmurne lub Burze) i łączy się z czytelną dla człowieka iconPhrase ikoną zwracaną obok niej. Ten sam kod może pojawiać się w bieżących, godzinowych, dziennych, kwartałowych i minutowych odpowiedziach, co pozwala aplikacjom wyświetlać spójny zestaw ikon dla wszystkich serwisów pogodowych.

Pełną listę kodów, ikon, do których się przypisują, oraz przykładowe obrazy można znaleźć w artykule Usługi pogodowe w Azure Maps.

JsonFormat

Żądany format odpowiedzi. Obsługiwany jest tylko format json.

SunGlare

Zagrożenie związane z odblaskami słonecznymi w jednym punkcie zwrotnym jako WaypointForecast.sunGlare. Raportuje od glareIndex0 do 100 pomiar intensywności odblasku, jaką kierowca doświadczyłby w punkcie nawigacyjnym, wraz z wykorzystaniem calculatedVehicleHeading do jego obliczenia – nagłówek to albo wartość podana dla punktu nawigacyjnego w żądaniu, albo jeśli nie została podana, to wartość wywnioskowana z sąsiednich punktów nawigacji.

UnitType

Wartość całkowita przypisana do typu wyświetlanej jednostki. Na przykład 17 dla stopni Celsjusza, 18 dla stopni Fahrenheita. Może być używany do przeliczania jednostek. Więcej informacji można znaleźć w Usługi pogodowe w Azure Maps.

WaypointForecast

Szczegółowa prognoza dla jednego punktu nawigacyjnego wzdłuż trasy drogowej, zwracana jako jeden wpis na każdy żądany punkt ( WeatherAlongRouteResult.waypoints w tej samej kolejności, co punkty nawigacyjne podane w żądaniu). Raportuje warunki w tym miejscu: reprezentatywne iconCode oraz shortPhrase, niezależnie od tego, czy jest dzień czy noc, zachmurzenie, temperatura, wiatr i podmuchy wiatru, typ i intensywność opadów, liczba uderzeń pioruna, zagrożenie odblasków słonecznych dla kierowcy, WeatherHazards suma na punkcie nawigacyjnym oraz wszelkie zagrożenia notificationso swobodnym charakterze.

WeatherAlongRoutePrecipitation

Oczekiwane opady w jednym punkcie na trasie zwracały jako WaypointForecast.precipitation. Prognozowana intensywność pokazuje odbicie radarowe (dbz) wraz z opadami type (deszcz, śnieg, lód, grad lub mieszanka). A dbz z 0 oznacza brak opadów, w takim przypadku type może być zwrócony, aby wskazać typ opadów, które wystąpiłyby , gdyby spadły w punkcie nawigacyjnym (na przykład śnieg podczas zimnej pogody).

WeatherAlongRouteResult

Odpowiedź powróciła dzięki operacji Get Weather Along Route, dostarczającej prognozę dla sekwencji punktów nawigacyjnych wzdłuż trasy drogowej. Zawiera najwyższy poziom summary z najwyższym wskaźnikiem zagrożeń na całej trasie oraz reprezentatywną ikonę pogody, a także tablicę waypoints zawierającą szczegółową prognozę dla każdego żądanego punktu nawigacyjnego – zachmurzenie, temperaturę, wiatr, opady, liczbę piorunow, odblaski słoneczne, zagrożenia i powiadomienia.

WeatherAlongRouteSummary

Podsumowanie na poziomie trasy na WeatherAlongRouteResult.summary, dające pojedynczy wysoki poziom ujęcia warunków na całej trasie. Zawiera reprezentatywną pogodę iconCode dla trasy oraz zagregowany hazards blok raportujący maksymalny indeks zagrożeń oraz konkretne typy zagrożeń napotkanych w dowolnym punkcie nawigacyjnym. Używaj go, gdy potrzebny jest pojedynczy wskaźnik poziomu trasy; dla szczegółów dla punktów nawigacyjnych użyj WeatherAlongRouteResult.waypoints.

WeatherHazards

Podsumowanie istotnych zagrożeń pogodowych w jednym miejscu. Ten sam kształt jest używany w dwóch miejscach w odpowiedzi Get Weather Along Route: na WeatherAlongRouteSummary.hazards, gdzie agreguje się na całej trasie (maksymalna intensywność na dowolnym punkcie nawigacyjnym), oraz na , WaypointForecast.hazardsgdzie opisuje zagrożenia w jednym konkretnym punkcie trasy. Pokazuje zarówno najwyższą ocenę maxHazardIndex największego zagrożenia w zasięgu (od 0 – brak zagrożenia – do 4 – zagrażający życiu), jak i tablicę hazardDetails wyliczającą każdy konkretny typ zagrożenia (deszcz, śnieg, lód, grad, odblask, błyskawice, wiatr oraz ostrzeżenia o gwałtownej pogodzie, takie jak powodzie, tornada, tsunami i silne burze).

WeatherNotification

Jedno wolne powiadomienie o zagrożeniu wywołane na jednym punkcie trasy, zwracane jako wpis w WaypointForecast.notifications. Każde powiadomienie łączy klasyfikację type powiadomienia, identyfikację hazardCode konkretnego zagrożenia, ocenę hazardIndex jego nasilenia w skali 0-4 oraz odpowiednie shortPhrase do wyświetlania. Powiadomienia WaypointForecast.hazards uzupełniają się – to drugie wymienia wszystkie aktywne zagrożenia na punkcie nawigacyjnym, a notifications obejmuje tylko te, które usługa oznaczyła jako warte pokazania kierowcy.

WeatherValue

Wartości dla wskaźników związanych z pogodą, takich jak temperatura, punkt rosy i prędkość wiatru, przedstawione w jednostkach metrycznych lub imperialnych, zgodnie z parametrem jednostkowym URI. Więcej informacji można znaleźć w artykule Typy jednostek w artykule Weather services in Azure Maps.

WindDetails

Dostarcza prognozowaną prędkość wiatru, mierzoną w jednostkach takich jak kilometry na godzinę (km/h) lub mile na godzinę (mph), w zależności od jednostki określonej w żądaniu. Wskazuje także kierunek wiatru mierzony w stopniach azymutu, zaczynając od prawdziwej północy i poruszając się zgodnie z ruchem wskazówek zegara. Północ odpowiada 0°, wschód 90°, południe 180°, a zachód 270°. Możliwe wartości wahają się od 0° do 359°.

WindDirection

Zawiera szczegóły dotyczące kierunku wiatru, w tym kierunek w stopniach azymutu oraz zlokalizowany skrót kierunku wiatru.