Compartilhar via

Weather - Get Weather Along Route

  • Referência
Serviço:
Maps
Versão da API:
1.1

Use para obter uma previsão localmente precisa e atualizada que inclua avaliações de risco meteorológico e notificações ao longo de uma rota.

A Get Weather Along Route API é uma solicitação HTTP GET que retorna hiper local (um quilômetro ou menos), agoracasts meteorológicos de até o minuto, avaliações de risco meteorológico e notificações ao longo de uma rota descrita como uma sequência de pontos de passagem. Isso inclui uma lista de riscos climáticos que afetam o ponto de passagem ou a rota, e o índice de risco agregado para cada ponto de passagem pode ser usado para pintar cada parte de uma rota de acordo com o quão seguro é para o driver. Ao enviar os pontos de passagem, é recomendável permanecer 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 Rota do Azure Mapas que permite primeiro solicitar uma rota entre uma origem e um destino e usá-la como entrada para o ponto de extremidade Clima ao Longo da Rota.

Além disso, o serviço dá suporte a cenários para gerar notificações meteorológicas para pontos de passagem que experimentam um aumento na intensidade de um risco climático. Por exemplo, se espera-se que o veículo comece a sofrer fortes chuvas à medida que atinge um ponto de passagem, uma notificação meteorológica para chuva forte será gerada para esse ponto de passagem, permitindo que o produto final exiba uma notificação de chuva forte antes que o motorista atinja esse ponto de passagem. O gatilho para quando exibir a notificação de um ponto de passagem pode ser baseado, por exemplo, em uma cerca geográfica ou distância selecionável até o ponto de passagem.

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

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

Parâmetros de URI

Nome Em Obrigatório Tipo Description
format
 path True

JsonFormat

Formato desejado da resposta. Há suporte apenas para o formato json.
api-version
 query True

string

Número de versão da API de Mapas Azure.
query
 query True

string

Coordenadas por meio das quais a rota é calculada, separadas por dois-pontos (:) e inseridas em ordem cronológica. Um mínimo de dois pontos de passagem é necessário. Uma única chamada à API pode conter até 60 pontos de passagem. Um ponto de passagem indica local, ETA e título opcional: latitude, longitude, ETA, título, onde

  • 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 atual que levará para o veículo chegar ao ponto de passagem. O intervalo permitido é de 0,0 a 120,0 minutos.
  • Heading – Um valor opcional que indica o título do veículo conforme ele passa pelo ponto de passagem. Expresso em graus no sentido horário em relação ao norte verdadeiro. Isso é 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 título será derivado automaticamente com base na posição dos pontos de passagem vizinhos.

É recomendável permanecer dentro ou perto da distância que pode ser percorrida dentro de 120 minutos ou pouco depois. Dessa forma, uma avaliação mais precisa pode ser fornecida 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 da rota (especialmente para viagens maiores que 2 horas) para puxar continuamente novos pontos de passagem para frente, mas também para garantir que as informações de previsão para conteúdo como tipo de precipitação e intensidade sejam 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 retornados. Deve ser uma das marcas de idioma IETF com suporte, que não diferencia maiúsculas de minúsculas. Quando os dados no idioma especificado não estão disponíveis para um campo específico, o idioma padrão é usado.

Consulte Idiomas com suporte para obter detalhes.

Cabeçalho da solicitação

Nome Obrigatório Tipo Description
x-ms-client-id

string

Especifica qual conta destina-se ao uso em conjunto com o modelo de segurança da ID do Microsoft Entra. Ele representa uma ID exclusiva para a conta do Azure Mapas e pode ser recuperado da API de Conta do plano de gerenciamento do Azure Mapas. Para usar a segurança do Microsoft Entra ID no Azure Mapas, confira os artigos a seguir para obter diretrizes .

Respostas

Nome Tipo Description
200 OK

WeatherAlongRouteResult

OK
Other Status Codes

ErrorResponse

Erro inesperado.

Segurança

AADToken

Estes são os Fluxos do Microsoft Entra OAuth 2.0 . Quando emparelhado com o controle de acesso baseado em função do Azure , ele pode ser usado para controlar o acesso às APIs REST do Azure Mapas. Os controles de acesso baseados em função do Azure são usados para designar o acesso a uma ou mais contas de recursos ou sub-recursos do Azure Mapas. Qualquer usuário, grupo ou entidade de serviço pode receber acesso por meio de uma função interna ou uma função personalizada composta por uma ou mais permissões para APIs REST do Azure Mapas.

Para implementar cenários, recomendamos exibir conceitos de autenticação. Em resumo, essa definição de segurança fornece uma solução para modelar aplicativos por meio de objetos capazes de acessar o controle em APIs e escopos específicos.

Observações

  • Essa definição de segurança requer o uso do x-ms-client-id cabeçalho para indicar a qual recurso do Azure Mapas o aplicativo está solicitando acesso. Isso pode ser adquirido da API de gerenciamento de Mapas .

O Authorization URL é específico para a instância de nuvem pública do Azure. As nuvens soberanas têm URLs de autorização exclusivas e configurações de ID do Microsoft Entra. * O controle de acesso baseado em função do Azure é configurado no plano de gerenciamento do Azure por meio do portal do Azure, do PowerShell, da CLI, dos SDKs do Azure ou das APIs REST. * O uso do SDK da Web do Azure Mapas permite a configuração baseada em configuração de um aplicativo para vários casos de uso.

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

Escopos

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

subscription-key

Essa é uma chave compartilhada provisionada quando você cria uma conta do Azure Mapas no portal do Azure ou usa o PowerShell, a CLI, os SDKs do Azure ou a API REST.

Com essa chave, qualquer aplicativo pode acessar toda a API REST. Em outras palavras, essa chave pode ser usada como uma chave mestra na conta em que elas são emitidas.

Para aplicativos expostos publicamente, nossa recomendação é usar a abordagem de aplicativos cliente confidenciais para acessar as APIs REST do Azure Mapas para que sua chave possa ser armazenada com segurança.

Tipo: apiKey
Em: query

SAS Token

Esse é um token de assinatura de acesso compartilhado criado a partir da operação Listar SAS no recurso do Azure Mapas por meio do plano de gerenciamento do Azure por meio do portal do Azure, do PowerShell, da CLI, dos SDKs do Azure ou das APIs REST.

Com esse token, qualquer aplicativo está autorizado a acessar com controles de acesso baseados em função do Azure e controle refinado para a expiração, a taxa e as regiões de uso para o token específico. Em outras palavras, o Token SAS pode ser usado para permitir que os aplicativos controlem o acesso de maneira mais segura do que a chave compartilhada.

Para aplicativos expostos publicamente, nossa recomendação é configurar uma lista específica de origens permitidas no recurso de conta de mapa para limitar o abuso de renderização e renovar regularmente o Token SAS.

Tipo: apiKey
Em: header

Exemplos

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

Solicitação de exemplo

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 de exemplo

Código de status:
200 
{
  "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

Nome Description
ErrorAdditionalInfo

As informações adicionais do erro de gerenciamento de recursos.
ErrorDetail

O detalhe do erro.
ErrorResponse

Resposta de erro
HazardDetail
HazardIndex

Um índice de gravidade/risco.

  • 0 - Sem perigo.
  • 1 - Esteja informado, esteja ciente.
  • 2 - Preste atenção, prepare-se.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.
IconCode

Valor numérico que representa uma imagem que exibe o iconPhrase. Consulte Serviços meteorológicos no Azure Mapas para obter detalhes.
JsonFormat

Formato desejado da resposta. Há suporte apenas para o formato json.
SunGlare

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

Valor de ID numérica associado ao tipo de unidade que está sendo exibida. Pode ser usado para tradução de unidade. Consulte Serviços meteorológicos no Azure Mapas para obter detalhes.
WeatherAlongRoutePrecipitation

Previsão de precipitação do tempo ao longo da rota.
WeatherAlongRouteResult

Esse objeto é retornado de um Weather Along Route bem-sucedido.
WeatherAlongRouteSummary

Resumo curto do tempo ao longo da rota.
WeatherHazards

Descrição do risco climático que afeta a viagem.
WeatherNotification
WeatherUnit

Valor específico de uma determinada unidade relacionada ao clima.
WeatherWaypoint
WindDetails

Detalhes do vento sendo retornados, incluindo velocidade e direção.
WindDirection

Direção do vento

ErrorAdditionalInfo

As informações adicionais do erro de gerenciamento de recursos.

Nome Tipo Description
info

object

As informações adicionais.
type

string

O tipo de informação adicional.

ErrorDetail

O detalhe do erro.

Nome 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 de erro

Nome Tipo Description
error

ErrorDetail

O objeto de erro.

HazardDetail

Nome Tipo Description
hazardCode

string

Um identificador exclusivo (não exibivel) para cada tipo de risco: 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 - Esteja informado, esteja ciente.
  • 2 - Preste atenção, prepare-se.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.
shortPhrase

string

Uma frase curta exibivel que descreve as condições previstas e a intensidade/tipo de precipitação.

HazardIndex

Um índice de gravidade/risco.

  • 0 - Sem perigo.
  • 1 - Esteja informado, esteja ciente.
  • 2 - Preste atenção, prepare-se.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.
Nome Tipo Description
0

Integer

1

Integer

2

Integer

3

Integer

4

Integer

IconCode

Valor numérico que representa uma imagem que exibe o iconPhrase. Consulte Serviços meteorológicos no Azure Mapas para obter detalhes.

Nome 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 desejado da resposta. Há suporte apenas para o formato json.

Nome Tipo Description
json

string

O formato de intercâmbio de dados de notação de objeto JavaScript

SunGlare

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

Nome Tipo Description
calculatedVehicleHeading

integer

Se o valor do título do veículo não for fornecido para um ponto de passagem, o serviço calculará um título com base no local dos pontos de passagem vizinhos, se fornecido.
glareIndex

integer

Um índice de 0 a 100 indicando intensidade de brilho solar para um driver. Um valor igual a 50 e superior pode ser considerado um risco para alguns motoristas e um valor de 100 significa que o motorista está dirigindo direto para o sol e as condições atmosféricas são claras, permitindo que toda a intensidade do sol cegar o motorista.

UnitType

Valor de ID numérica associado ao tipo de unidade que está sendo exibida. Pode ser usado para tradução de unidade. Consulte Serviços meteorológicos no Azure Mapas para obter detalhes.

Nome 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 da rota.

Nome Tipo Description
dbz

number

A intensidade de precipitação prevista no 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á: "RAIN", "HAIL", "SNOW", "ICE" ou "MIX".

WeatherAlongRouteResult

Esse objeto é retornado de um Weather Along Route bem-sucedido.

Nome Tipo Description
summary

WeatherAlongRouteSummary

Resumo curto do tempo ao longo da rota.
waypoints

WeatherWaypoint[]

Dados de cada ponto de passagem retornados na mesma ordem especificada na solicitação.

WeatherAlongRouteSummary

Resumo curto do tempo ao longo da rota.

Nome Tipo Description
hazards

WeatherHazards

Descrição do risco climático que afeta a viagem.
iconCode

IconCode

Valor numérico que representa uma imagem que exibe o iconPhrase. Consulte Serviços meteorológicos no Azure Mapas para obter detalhes.

WeatherHazards

Descrição do risco climático que afeta a viagem.

Nome Tipo Description
hazardDetails

HazardDetail[]

Detalhes dos perigos climáticos que afetam a viagem.
maxHazardIndex

HazardIndex

Um índice de gravidade/risco.

  • 0 - Sem perigo.
  • 1 - Esteja informado, esteja ciente.
  • 2 - Preste atenção, prepare-se.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.

WeatherNotification

Nome Tipo Description
hazardCode

string

Um identificador exclusivo (não exibivel) para cada tipo de risco: 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 - Esteja informado, esteja ciente.
  • 2 - Preste atenção, prepare-se.
  • 3 - Tome medidas.
  • 4 - Risco de vida, emergência.
shortPhrase

string

Uma frase curta exibivel que descreve as condições previstas e a intensidade/tipo de precipitação.
type

string

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

WeatherUnit

Valor específico de uma determinada unidade relacionada ao clima.

Nome Tipo Description
unit

string

Tipo de unidade para o valor retornado.
unitType

UnitType

Valor de ID numérica associado ao tipo de unidade que está sendo exibida. Pode ser usado para tradução de unidade. Consulte Serviços meteorológicos no Azure Mapas para obter detalhes.
value

number

Valor arredondado.

WeatherWaypoint

Nome Tipo Description
cloudCover

integer

Porcentagem que representa a cobertura de nuvem.
hazards

WeatherHazards

Descrição do risco climático que afeta a viagem.
iconCode

IconCode

Valor numérico que representa uma imagem que exibe o iconPhrase. Consulte Serviços meteorológicos no Azure Mapas para obter detalhes.
isDayTime

boolean

Indica a hora do dia. True indica 'day',', false indica 'night.
lightningCount

integer

Estimativa da intensidade da tempestade em escala aberta. Um valor igual a 0 significa que não há tempestade; valores de 1 e maior média há uma tempestade em intensidade crescente.
notifications

WeatherNotification[]

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

WeatherAlongRoutePrecipitation

Previsão de precipitação do tempo ao longo da rota.
shortPhrase

string

Uma frase curta exibivel 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 driver.
temperature

WeatherUnit

Valor específico de uma determinada unidade relacionada ao clima.
wind

WindDetails

Detalhes do vento sendo retornados, incluindo velocidade e direção.
windGust

WindDetails

Detalhes do vento sendo retornados, incluindo velocidade e direção.

WindDetails

Detalhes do vento sendo retornados, incluindo velocidade e direção.

Nome Tipo Description
direction

WindDirection

Direção do vento
speed

WeatherUnit

Velocidade do vento na unidade especificada.

WindDirection

Direção do vento

Nome Tipo Description
degrees

integer

Direção do vento em graus de Azimuth, começando no verdadeiro Norte e continuando na direção no sentido horário. Norte é 0 graus, leste é 90 graus, sul é 180 graus, oeste é 270 graus. Valores possíveis de 0 a 359.
localizedDescription

string

Abreviação de direção no idioma especificado.