Partilhar via


Weather - Get Weather Along Route

Utilizado para obter uma previsão de localização precisa e atualizada que inclua avaliações de riscos meteorológicos e notificações ao longo de uma rota.

A Get Weather Along Route API é um pedido HTTP GET que devolve hiper local (um quilómetro ou menos), nowcasts meteorológicos atualizados, avaliações de riscos meteorológicos e notificações ao longo de uma rota descrita como uma sequência de pontos de passagem. Isto inclui uma lista de riscos meteorológicos que afetam o waypoint ou a rota, e o índice de risco agregado para cada ponto de caminho pode ser utilizado para pintar cada parte de uma rota de acordo com o quão seguro é para o controlador. Ao submeter os pontos de passagem, recomenda-se que se mantenha dentro ou perto da distância que pode ser percorrida dentro de 120 minutos ou pouco depois. Os dados são atualizados a cada cinco minutos.

O serviço complementa o Serviço de Rotas do Azure Maps que lhe permite pedir primeiro uma rota entre uma origem e um destino e utilizá-la como entrada para o ponto final Meteorologia Ao Longo da Rota.

Além disso, o serviço suporta cenários para gerar notificações meteorológicas para pontos de passagem que experimentam um aumento na intensidade de um risco meteorológico. Por exemplo, se se espera que o veículo comece a sofrer chuva intensa à medida que atinge um ponto de passagem, será gerada uma notificação meteorológica para chuva intensa para esse ponto de passagem, permitindo que o produto final apresente uma notificação de chuva intensa antes de o condutor chegar a esse ponto de passagem. O acionador para quando apresentar a notificação de um ponto de passagem pode basear-se, por exemplo, num perímetro geográfico ou numa distância selecionável até ao ponto de passagem.

A API abrange todas as regiões do planeta, exceto as latitudes acima da Gronelândia e da Antártida.

GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query={query}
GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query={query}&language={language}

Parâmetros do URI

Name Em Necessário Tipo Description
format
path True

JsonFormat

Formato pretendido da resposta. Apenas json o formato é suportado.

api-version
query True

string

Número da versão da API do Azure Maps.

query
query True

string

Coordenadas através das quais a rota é calculada, separada por dois pontos (:) e introduzida por ordem cronológica. É necessário um mínimo de dois pontos de passagem. Uma única chamada à API pode conter até 60 pontos de passagem. Um waypoint indica a localização, o ETA e o cabeçalho opcional: latitude,longitude,ETA,cabeçalho, em que

  • Latitude - Coordenada de latitude em graus decimais.
  • Longitude - Coordenada de longitude em graus decimais.
  • ETA (estimated time of arrival) - O número de minutos a partir do momento em que o veículo irá demorar a chegar ao ponto de passagem. O intervalo permitido é de 0,0 a 120,0 minutos.
  • Heading - Um valor opcional que indica o cabeçalho do veículo à medida que passa pelo ponto de passagem. Expresso em graus no sentido dos ponteiros do relógio em relação ao verdadeiro norte. Isto é emitido para calcular o brilho solar como um risco de condução. O intervalo permitido é de 0,0 a 360,0 graus. Se não for fornecido, um cabeçalho será obtido automaticamente com base na posição dos pontos de passagem vizinhos.

Recomenda-se que se mantenha dentro ou perto da distância que pode ser percorrida dentro de 120 minutos ou pouco depois. Desta forma, pode ser fornecida uma avaliação mais precisa para a viagem e impedir que eventos isolados não sejam capturados entre pontos de passagem. As informações podem e devem ser atualizadas ao longo do percurso (especialmente para viagens superiores a 2 horas) para puxar continuamente novos pontos de passagem, mas também para garantir que as informações de previsão para conteúdo como o tipo de precipitação e intensidade são precisas à medida que as tempestades se desenvolvem e se dissipam ao longo do tempo.

language
query

string

Idioma no qual os resultados da pesquisa devem ser devolvidos. Deve ser uma das etiquetas de linguagem IETF suportadas, não sensível a maiúsculas e minúsculas. Quando os dados no idioma especificado não estão disponíveis para um campo específico, é utilizado o idioma predefinido.

Consulte idiomas suportados para obter detalhes.

Cabeçalho do Pedido

Name Necessário Tipo Description
x-ms-client-id

string

Especifica a conta que se destina à utilização em conjunto com o modelo de segurança Microsoft Entra ID. Representa um ID exclusivo para a conta do Azure Maps e pode ser obtido a partir da API de Conta do plano de gestão do Azure Maps. Para utilizar a segurança do Microsoft Entra ID no Azure Maps, consulte os seguintes artigos para obter orientações.

Respostas

Name Tipo Description
200 OK

WeatherAlongRouteResult

OK

Other Status Codes

ErrorResponse

Ocorreu um erro inesperado.

Segurança

AADToken

Estes são os Fluxos Microsoft Entra OAuth 2.0 . Quando emparelhado com o controlo de acesso baseado em funções do Azure , pode ser utilizado para controlar o acesso às APIs REST do Azure Maps. Os controlos de acesso baseados em funções do Azure são utilizados para designar o acesso a uma ou mais contas de recursos ou sub-recursos do Azure Maps. Qualquer utilizador, grupo ou principal de serviço pode ter acesso através de uma função incorporada ou de uma função personalizada composta por uma ou mais permissões para as APIs REST do Azure Maps.

Para implementar cenários, recomendamos que veja os conceitos de autenticação. Em resumo, esta definição de segurança fornece uma solução para modelar aplicações através de objetos com capacidade de controlo de acesso em APIs e âmbitos específicos.

Notas

  • Esta definição de segurança requer a utilização do x-ms-client-id cabeçalho para indicar a que recurso do Azure Maps a aplicação está a pedir acesso. Isto pode ser adquirido a partir da API de gestão do Maps .

O Authorization URL é específico da instância da cloud pública do Azure. As clouds soberanas têm URLs de Autorização exclusivos e configurações do Microsoft Entra ID. * O controlo de acesso baseado em funções do Azure está configurado a partir do plano de gestão do Azure através do portal do Azure, do PowerShell, da CLI, dos SDKs do Azure ou das APIs REST. * A utilização do SDK Web do Azure Maps permite a configuração baseada na configuração de uma aplicação para vários casos de utilização.

Tipo: oauth2
Fluxo: implicit
URL de Autorização: https://login.microsoftonline.com/common/oauth2/authorize

Âmbitos

Name Description
https://atlas.microsoft.com/.default https://atlas.microsoft.com/.default

subscription-key

Esta é uma chave partilhada que é aprovisionada quando Cria uma conta do Azure Maps no portal do Azure ou com o PowerShell, a CLI, os SDKs do Azure ou a API REST.

Com esta chave, qualquer aplicação pode aceder a toda a API REST. Por outras palavras, esta chave pode ser utilizada como uma chave mestra na conta na qual são emitidas.

Para aplicações expostas publicamente, a nossa recomendação é utilizar a abordagem de aplicações cliente confidenciais para aceder às APIs REST do Azure Maps para que a sua chave possa ser armazenada em segurança.

Tipo: apiKey
Em: query

SAS Token

Este é um token de assinatura de acesso partilhado criado a partir da operação Listar SAS no recurso do Azure Maps através do plano de gestão do Azure através do portal do Azure, do PowerShell, da CLI, dos SDKs do Azure ou das APIs REST.

Com este token, qualquer aplicação está autorizada a aceder com controlos de acesso baseados em funções do Azure e controlo detalhado para a expiração, taxa e regiões de utilização para o token específico. Por outras palavras, o Token de SAS pode ser utilizado para permitir que as aplicações controlem o acesso de uma forma mais segura do que a chave partilhada.

Para aplicações expostas publicamente, a nossa recomendação é configurar uma lista específica de origens permitidas no recurso da conta de Mapa para limitar o abuso de composição e renovar regularmente o Token de SAS.

Tipo: apiKey
Em: header

Exemplos

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

Pedido de amostra

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

Resposta da amostra

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

Definições

Name Description
ErrorAdditionalInfo

Informações adicionais sobre o erro de gestão de recursos.

ErrorDetail

O detalhe do erro.

ErrorResponse

Resposta a erros

HazardDetail
HazardIndex

Um índice de gravidade/risco.

  • 0 - Sem perigo.
  • 1 - Seja informado, tenha em atenção.
  • 2 Preste atenção, esteja preparado.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.
IconCode

Valor numérico que representa uma imagem que apresenta o iconPhrase. Veja Serviços de meteorologia no Azure Maps para obter detalhes.

JsonFormat

Formato pretendido da resposta. Apenas json o formato é suportado.

SunGlare

Uma classificação que indica o quão ofuscante é o sol para o condutor.

UnitType

Valor de ID numérico associado ao tipo de unidade que está a ser apresentada. Pode ser utilizado para tradução de unidades. Veja Serviços de meteorologia no Azure Maps para obter detalhes.

WeatherAlongRoutePrecipitation

Previsão de precipitação do tempo ao longo do percurso.

WeatherAlongRouteResult

Este objeto é devolvido de uma Meteorologia bem-sucedida ao longo da rota.

WeatherAlongRouteSummary

Breve resumo da meteorologia ao longo do percurso.

WeatherHazards

Descrição do risco meteorológico que afeta a viagem.

WeatherNotification
WeatherUnit

Valor específico de uma determinada unidade relacionada com a meteorologia.

WeatherWaypoint
WindDetails

Detalhes do vento a serem devolvidos, incluindo velocidade e direção.

WindDirection

Direção do vento

ErrorAdditionalInfo

Informações adicionais sobre o erro de gestão de recursos.

Name Tipo Description
info

object

As informações adicionais.

type

string

O tipo de informações adicionais.

ErrorDetail

O detalhe do erro.

Name Tipo Description
additionalInfo

ErrorAdditionalInfo[]

As informações adicionais do erro.

code

string

O código de erro.

details

ErrorDetail[]

Os detalhes do erro.

message

string

A mensagem de erro.

target

string

O destino do erro.

ErrorResponse

Resposta a erros

Name Tipo Description
error

ErrorDetail

O objeto de erro.

HazardDetail

Name Tipo Description
hazardCode

string

Um identificador exclusivo (não apresentável) para cada tipo de perigo: LightRain, ModerateRain, HeavyRain, LightMix, ModerateMix, HeavyMix, LightSnow, ModerateSnow, HeavySnow, LightIce, ModerateIce, HeavyIce, Hail, LargeHail, SunGlare, SunGlareHigh, Lightning, SevereLightning, WindModerate, WindHigh, WindExtreme, FloodWarning, FlashFloodWarning, TornadoWarning, TsunamiWarning, SevereThunderstormWarning.

hazardIndex

HazardIndex

Um índice de gravidade/risco.

  • 0 - Sem perigo.
  • 1 - Seja informado, tenha em atenção.
  • 2 Preste atenção, esteja preparado.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.
shortPhrase

string

Uma expressão curta apresentável que descreve as condições previstas e a intensidade/tipo de precipitação.

HazardIndex

Um índice de gravidade/risco.

  • 0 - Sem perigo.
  • 1 - Seja informado, tenha em atenção.
  • 2 Preste atenção, esteja preparado.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.
Name Tipo Description
0

Integer

1

Integer

2

Integer

3

Integer

4

Integer

IconCode

Valor numérico que representa uma imagem que apresenta o iconPhrase. Veja Serviços de meteorologia no Azure Maps para obter detalhes.

Name Tipo Description
1

Integer

10

Integer

11

Integer

12

Integer

13

Integer

14

Integer

15

Integer

16

Integer

17

Integer

18

Integer

19

Integer

2

Integer

20

Integer

21

Integer

22

Integer

23

Integer

24

Integer

25

Integer

26

Integer

27

Integer

28

Integer

29

Integer

3

Integer

30

Integer

31

Integer

32

Integer

33

Integer

34

Integer

35

Integer

36

Integer

37

Integer

38

Integer

39

Integer

4

Integer

40

Integer

41

Integer

42

Integer

43

Integer

44

Integer

5

Integer

6

Integer

7

Integer

8

Integer

9

Integer

JsonFormat

Formato pretendido da resposta. Apenas json o formato é suportado.

Name Tipo Description
json

string

Formato JavaScript Object Notation Data Interchange

SunGlare

Uma classificação que indica o quão ofuscante é o sol para o condutor.

Name Tipo Description
calculatedVehicleHeading

integer

Se o valor do cabeçalho do veículo não for fornecido para um ponto de passagem, o serviço calculará um cabeçalho com base na localização dos pontos de passagem vizinhos, se fornecido.

glareIndex

integer

Um índice de 0 a 100 a indicar intensidade de brilho solar para um condutor. Um valor igual ou superior a 50 pode ser considerado um perigo para alguns condutores e um valor de 100 significa que o condutor está a conduzir directamente para o sol e as condições atmosféricas são claras, permitindo que toda a intensidade do sol blinde o condutor.

UnitType

Valor de ID numérico associado ao tipo de unidade que está a ser apresentada. Pode ser utilizado para tradução de unidades. Veja Serviços de meteorologia no Azure Maps para obter detalhes.

Name Tipo Description
0

Integer

1

Integer

10

Integer

11

Integer

12

Integer

13

Integer

14

Integer

15

Integer

16

Integer

17

Integer

18

Integer

19

Integer

2

Integer

20

Integer

21

Integer

22

Integer

3

Integer

31

Integer

4

Integer

5

Integer

6

Integer

7

Integer

8

Integer

9

Integer

WeatherAlongRoutePrecipitation

Previsão de precipitação do tempo ao longo do percurso.

Name Tipo Description
dbz

number

A intensidade de precipitação prevista em dBZ (decibéis relativos a Z) de 0,0 a 100,0.

type

string

Tipo de precipitação. Se a precipitação ocorrer, o tipo que será: "CHUVA", "GRANIZO", "NEVE", "GELO" ou "MIX".

WeatherAlongRouteResult

Este objeto é devolvido de uma Meteorologia bem-sucedida ao longo da rota.

Name Tipo Description
summary

WeatherAlongRouteSummary

Breve resumo da meteorologia ao longo do percurso.

waypoints

WeatherWaypoint[]

Dados para cada ponto de passagem devolvido pela mesma ordem especificada no pedido.

WeatherAlongRouteSummary

Breve resumo da meteorologia ao longo do percurso.

Name Tipo Description
hazards

WeatherHazards

Descrição do risco meteorológico que afeta a viagem.

iconCode

IconCode

Valor numérico que representa uma imagem que apresenta o iconPhrase. Veja Serviços de meteorologia no Azure Maps para obter detalhes.

WeatherHazards

Descrição do risco meteorológico que afeta a viagem.

Name Tipo Description
hazardDetails

HazardDetail[]

Detalhes dos perigos meteorológicos que afetam a viagem.

maxHazardIndex

HazardIndex

Um índice de gravidade/risco.

  • 0 - Sem perigo.
  • 1 - Seja informado, tenha em atenção.
  • 2 Preste atenção, esteja preparado.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.

WeatherNotification

Name Tipo Description
hazardCode

string

Um identificador exclusivo (não apresentável) para cada tipo de perigo: LightRain, ModerateRain, HeavyRain, LightMix, ModerateMix, HeavyMix, LightSnow, ModerateSnow, HeavySnow, LightIce, ModerateIce, HeavyIce, Hail, LargeHail, SunGlare, SunGlareHigh, Lightning, SevereLightning, WindModerate, WindHigh, WindExtreme, FloodWarning, FlashFloodWarning, TornadoWarning, TsunamiWarning, SevereThunderstormWarning.

hazardIndex

HazardIndex

Um índice de gravidade/risco.

  • 0 - Sem perigo.
  • 1 - Seja informado, tenha em atenção.
  • 2 Preste atenção, esteja preparado.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.
shortPhrase

string

Uma expressão curta apresentável que descreve as condições previstas e a intensidade/tipo de precipitação.

type

string

Um tipo de notificação gerada para alertar os condutores sobre o início de um perigo ou aumentar a intensidade de um perigo.

WeatherUnit

Valor específico de uma determinada unidade relacionada com a meteorologia.

Name Tipo Description
unit

string

Tipo de unidade para o valor devolvido.

unitType

UnitType

Valor de ID numérico associado ao tipo de unidade que está a ser apresentada. Pode ser utilizado para tradução de unidades. Veja Serviços de meteorologia no Azure Maps para obter detalhes.

value

number

Valor arredondado.

WeatherWaypoint

Name Tipo Description
cloudCover

integer

Percentagem que representa a cobertura da cloud.

hazards

WeatherHazards

Descrição do risco meteorológico que afeta a viagem.

iconCode

IconCode

Valor numérico que representa uma imagem que apresenta o iconPhrase. Veja Serviços de meteorologia no Azure Maps para obter detalhes.

isDayTime

boolean

Indica a hora do dia. True indica "dia", "" falso indica "noite".

lightningCount

integer

Estimativa de intensidade de trovoada em escala aberta. Um valor de 0 significa que não há trovoada; valores de 1 e média superior há uma trovoada em intensidade crescente.

notifications

WeatherNotification[]

Lista de notificações de risco meteorológico.

precipitation

WeatherAlongRoutePrecipitation

Previsão de precipitação do tempo ao longo do percurso.

shortPhrase

string

Uma expressão curta apresentável que descreve as condições previstas e a intensidade/tipo de precipitação.

sunGlare

SunGlare

Uma classificação que indica o quão ofuscante é o sol para o condutor.

temperature

WeatherUnit

Valor específico de uma determinada unidade relacionada com a meteorologia.

wind

WindDetails

Detalhes do vento a serem devolvidos, incluindo velocidade e direção.

windGust

WindDetails

Detalhes do vento a serem devolvidos, incluindo velocidade e direção.

WindDetails

Detalhes do vento a serem devolvidos, incluindo velocidade e direção.

Name Tipo Description
direction

WindDirection

Direção do vento

speed

WeatherUnit

Velocidade do vento na unidade especificada.

WindDirection

Direção do vento

Name Tipo Description
degrees

integer

Direção do vento em graus de Azimuto, começando no verdadeiro Norte e continuando no sentido dos ponteiros do relógio. Norte é 0 graus, leste é 90 graus, sul é 180 graus, oeste é 270 graus. Valores possíveis 0-359.

localizedDescription

string

Abreviatura de direção no idioma especificado.