Weather Data - Get

Reference

Service:: Azure Data Manager for Agriculture

API Version:: 2023-11-01-preview

Returns a list of WeatherData.

POST {endpoint}/weather-data:fetch?api-version=2023-11-01-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string uri	The host name of the namespace, e.g. admaInstanceName.farmbeats.azure.net
api-version	query	True	string	The requested API version

Request Header

Name	Required	Type	Description
Authorization	True	string	Please provide a valid bearer token for authorized API calls. Note that you might need to clear your browser cache if you tried un-authenticated calls before.

Request Body

Name	Required	Type	Description
extensionApiName	True	string	Extension api name to which request is to be made.
extensionId	True	string	Id of the extension to be used for the providerInput. eg. DTN.ClearAg.
units	True	string	Units for which request to data provider is to be sent. Supported values are 'e' for English units, 'm' for Metric units, 'h' for Hybrid units (UK) and 's' for Metric SI units.
additionalParams		AdditionalProviderParameters	Schema of additional parameters for weather data provider request.
credentials		ApiKeyAuthCredentials	Api Key Auth Credentials class for API Key based Auth.
duration		integer	Specifies for how many days the daily forecast responses are returned. Available values are 1, 5, 10, 25 and 45. (Only applicable for Azure Weather Maps extension.)
endTimeHours		integer	End of time range. (Only applicable for DTN.ClearAg extension.)
language		string	Language (IETF BCP 47 language tag) in which search results should be returned by the data provider. Examples: 'en-US', 'es', 'es-MX', 'fr-FR'.
locations		WeatherLocation[]	List of locations for which weather data need to be fetched from the provider.
startTimeHours		integer	Start of time range. Hour 0 represents the current hour. (Only applicable for DTN.ClearAg extension.)

Responses

Name	Type	Description
200 OK	WeatherDataProviderResponse	Success
Other Status Codes	ErrorResponse	Error Headers x-ms-error-code: string

Name

Type

Description

200 OK

WeatherDataProviderResponse

Success

Other Status Codes

ErrorResponse

Error

Headers

x-ms-error-code: string

Security

Authorization

Please provide a valid bearer token for authorized API calls. Note that you might need to clear your browser cache if you tried un-authenticated calls before.

Type: apiKey
In: header

Examples

WeatherData_Get

Sample request

HTTP

POST {endpoint}/weather-data:fetch?api-version=2023-11-01-preview

{
  "extensionId": "IBM.TWC",
  "extensionApiName": "currents-on-demand",
  "locations": [
    {
      "type": "LatLong",
      "value": "33,-97"
    }
  ],
  "language": "en-US",
  "units": "e",
  "credentials": {
    "kind": "ApiKeyAuthCredentials",
    "apiKey": {
      "keyVaultUri": "https://<keyvaultname>.vault.azure.net/",
      "keyName": "string",
      "keyVersion": "string"
    }
  }
}

Sample response

Status code:: 200

{
  "weatherMetadata": {
    "extensionVersion": "1.0",
    "weatherDataType": "current",
    "extensionId": "IBM.TWC",
    "extensionApiName": "currents-on-demand",
    "units": "e"
  },
  "status": "Succeeded",
  "locations": [
    {
      "location": {
        "type": "LatLong",
        "value": "33,-97"
      },
      "lastRefreshedDateTime": "2023-02-09T13:02:20Z",
      "data": {
        "dayOfWeek": [
          "Wednesday"
        ],
        "dayOrNight": [
          "Night"
        ],
        "pressureMeanSeaLevel": {
          "unit": "inches of mercury",
          "value": [
            1021.1
          ]
        },
        "relativeHumidity": {
          "unit": "percentage",
          "value": [
            84
          ]
        },
        "temperature": {
          "unit": "fahrenheit",
          "value": [
            49
          ]
        },
        "temperatureDewPoint": {
          "unit": "fahrenheit",
          "value": [
            44
          ]
        },
        "temperatureFeelsLike": {
          "unit": "fahrenheit",
          "value": [
            47
          ]
        },
        "temperatureHeatIndex": {
          "unit": "fahrenheit",
          "value": [
            49
          ]
        },
        "temperatureWindChill": {
          "unit": "fahrenheit",
          "value": [
            47
          ]
        },
        "uvDescription": [
          "Low"
        ],
        "uvIndex": [
          0
        ],
        "visibility": {
          "unit": "miles",
          "value": [
            10
          ]
        },
        "windDirection": {
          "unit": "degree",
          "value": [
            150
          ]
        },
        "windGust": {
          "unit": "miles/hour",
          "value": [
            0
          ]
        },
        "windSpeed": {
          "unit": "miles/hour",
          "value": [
            4
          ]
        },
        "additionalAttributes": {
          "cloudCoverPhrase": [
            "Partly Cloudy"
          ]
        }
      }
    }
  ],
  "errors": {
    "locations": []
  }
}

Definitions

Name	Description
AdditionalProviderParameters	Schema of additional parameters for weather data provider request.
ApiKeyAuthCredentials	Api Key Auth Credentials class for API Key based Auth.
AuthCredentialsKind	Enum for different types of AuthCredentials supported.
Error	An error from the Azure AgPlatform service.
ErrorForLocation	Model for error information for a failed location.
ErrorResponse	An error response from the Azure AgPlatform service. See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses for ErrorResponse reference document.
InnerError	Inner error containing list of errors.See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#innererror--object for InnerError reference document.
KeyVaultProperties	Properties of the key vault.
LocationType	Location Type eg. LatLong/IataCode/IcaoCode/Placeid/PostalKey.
Measures	Schema for storing measurement readings and unit.
Status	Indicates a Succeeded, Failed, or PartiallySucceeded response.
WeatherDataErrors	Model for errors encountered for all failed locations.
WeatherDataForPassthrough	Schema of weather data.
WeatherDataProviderRequest	Schema of weather data provider request.
WeatherDataProviderResponse	Schema of Weather Data Provider Response.
WeatherLocation	Schema of Location data.
WeatherLocationData	Schema of WeatherLocationData data.
WeatherMetadata	Schema of Weather Metadata.

AdditionalProviderParameters

Schema of additional parameters for weather data provider request.

Name	Type	Default value	Description
details	boolean	True	Details (Only applicable for AzureWeatherMaps).
iconResolution	string		Icon Resolution (Only applicable for AzureWeatherMaps).

ApiKeyAuthCredentials

Api Key Auth Credentials class for API Key based Auth.

Name	Type	Description
apiKey	KeyVaultProperties	Properties of the key vault.
kind	string: ApiKeyAuthCredentials	Enum for different types of AuthCredentials supported.

AuthCredentialsKind

Enum for different types of AuthCredentials supported.

Name	Type	Description
ApiKeyAuthCredentials	string
OAuthClientCredentials	string

Error

An error from the Azure AgPlatform service.

Name	Type	Description
code	string	Server-defined set of error codes.
details	Error[]	Array of details about specific errors that led to this reported error.
innererror	InnerError	Inner error containing list of errors.See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#innererror--object for InnerError reference document.
message	string	Human-readable representation of the error.
target	string	Target of the error.

ErrorForLocation

Model for error information for a failed location.

Name	Type	Description
code	integer	Status code returned by data provider.
description	string	Description of the error.
location	WeatherLocation	Schema of Location data.
retryable	boolean	Flag suggesting if retry attempt with same request body should be made to fetch required data.

ErrorResponse

An error response from the Azure AgPlatform service. See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses for ErrorResponse reference document.

Name	Type	Description
error	Error	An error from the Azure AgPlatform service.
traceId	string	Unique trace Id.

InnerError

Inner error containing list of errors.See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#innererror--object for InnerError reference document.

Name	Type	Description
code	string	Specific error code than was provided by the containing error.
innererror	InnerError	Inner error containing list of errors.See https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#innererror--object for InnerError reference document.

KeyVaultProperties

Properties of the key vault.

Name	Type	Description
keyName	string	Name of Key Vault key.
keyVaultUri	string	Uri of the key vault.
keyVersion	string	Version of Key Vault key.

LocationType

Location Type eg. LatLong/IataCode/IcaoCode/Placeid/PostalKey.

Name	Type	Description
IataCode	string
IcaoCode	string
LatLong	string
PlaceId	string
PostalKey	string

Measures

Schema for storing measurement readings and unit.

Name	Type	Description
unit	string	Data unit.
value	number[]	Data values.

Status

Indicates a Succeeded, Failed, or PartiallySucceeded response.

Name	Type	Description
Failed	string
PartiallySucceeded	string
Succeeded	string

WeatherDataErrors

Model for errors encountered for all failed locations.

Name	Type	Description
locations	ErrorForLocation[]	List of errors encountered for all failed locations.

WeatherDataForPassthrough

Schema of weather data.

Name	Type	Description
additionalAttributes		A collection of key value pairs that belongs to the resource. Each pair must not have a key greater than 50 characters and must not have a value greater than 250 characters. Note: A maximum of 100 key value pairs can be provided for a resource and only string and numeral values are supported.
cloudCover	Measures	Schema for storing measurement readings and unit.
dayOfWeek	string[]	Day of week.
dayOrNight	string[]	This data field indicates whether it is daytime or nighttime based on the Local Apparent Time of the location.
expirationTime	string[]	Expiration time in Utc format.
hasPrecipitation	boolean[]	Indicates whether there is precipitation or not.
iconCode	integer[]	This number is the key to the weather icon lookup. The data field shows the icon number that is matched to represent the observed weather conditions.
iconCodeExtend	integer[]	Code representing full set sensible weather.
pressureMeanSeaLevel	Measures	Schema for storing measurement readings and unit.
relativeHumidity	Measures	Schema for storing measurement readings and unit.
temperature	Measures	Schema for storing measurement readings and unit.
temperatureDewPoint	Measures	Schema for storing measurement readings and unit.
temperatureFeelsLike	Measures	Schema for storing measurement readings and unit.
temperatureHeatIndex	Measures	Schema for storing measurement readings and unit.
temperatureWindChill	Measures	Schema for storing measurement readings and unit.
uvDescription	string[]	The UV Index Description which complements the UV Index value by providing an associated level of risk of skin damage due to exposure (-2 = Not Available, -1 = No Report, 0 to 2 = Low, 3 to 5 = Moderate, 6 to 7 = High, 8 to 10 = Very High, 11 to 16 = Extreme).
uvIndex	number[]	Hourly maximum UV index.
validTime	string[]	Time forecast is valid in Utc format.
validTimeLocal	string[]	Time forecast is valid in local apparent time.
visibility	Measures	Schema for storing measurement readings and unit.
wetBulbTemperature	Measures	Schema for storing measurement readings and unit.
windDirection	Measures	Schema for storing measurement readings and unit.
windGust	Measures	Schema for storing measurement readings and unit.
windSpeed	Measures	Schema for storing measurement readings and unit.
wxPhraseLong	string[]	Hourly sensible weather phrase containing longer description.
wxPhraseShort	string[]	Hourly sensible weather phrase containing short description.

WeatherDataProviderRequest

Schema of weather data provider request.

Name	Type	Description
additionalParams	AdditionalProviderParameters	Schema of additional parameters for weather data provider request.
credentials	ApiKeyAuthCredentials	Api Key Auth Credentials class for API Key based Auth.
duration	integer	Specifies for how many days the daily forecast responses are returned. Available values are 1, 5, 10, 25 and 45. (Only applicable for Azure Weather Maps extension.)
endTimeHours	integer	End of time range. (Only applicable for DTN.ClearAg extension.)
extensionApiName	string	Extension api name to which request is to be made.
extensionId	string	Id of the extension to be used for the providerInput. eg. DTN.ClearAg.
language	string	Language (IETF BCP 47 language tag) in which search results should be returned by the data provider. Examples: 'en-US', 'es', 'es-MX', 'fr-FR'.
locations	WeatherLocation[]	List of locations for which weather data need to be fetched from the provider.
startTimeHours	integer	Start of time range. Hour 0 represents the current hour. (Only applicable for DTN.ClearAg extension.)
units	string	Units for which request to data provider is to be sent. Supported values are 'e' for English units, 'm' for Metric units, 'h' for Hybrid units (UK) and 's' for Metric SI units.

WeatherDataProviderResponse

Schema of Weather Data Provider Response.

Name	Type	Description
errors	WeatherDataErrors	Model for errors encountered for all failed locations.
locations	WeatherLocationData[]	List of weather data for all the weather locations.
status	Status	Indicates a Succeeded, Failed, or PartiallySucceeded response.
weatherMetadata	WeatherMetadata	Schema of Weather Metadata.

WeatherLocation

Schema of Location data.

Name	Type	Description
type	LocationType	Location Type eg. LatLong/IataCode/IcaoCode/Placeid/PostalKey.
value	string	Location Value eg. "10,-25" for LocationType Type "LatLong".

WeatherLocationData

Schema of WeatherLocationData data.

Name	Type	Description
data	WeatherDataForPassthrough	Schema of weather data.
lastRefreshedDateTime	string	Date-time when resource was last requested, sample format: yyyy-MM-ddTHH:mm:ssZ.
location	WeatherLocation	Schema of Location data.
requestCompletionTime	string	Request Completion Time in Utc of the location.

WeatherMetadata

Schema of Weather Metadata.

Name	Type	Description
additionalParams	AdditionalProviderParameters	Schema of additional parameters for weather data provider request.
duration	integer	Specifies for how many days the daily forecast responses are returned. Available values are 1, 5, 10, 25 and 45. (Only applicable for Azure Weather Maps extension.)
endTimeHours	integer	End of time range. (Only applicable for DTN.ClearAg extension.)
extensionApiName	string	Extension api name to which request is to be made.
extensionId	string	Id of the extension to be used for the providerInput. eg. DTN.ClearAg.
extensionVersion	string	Version of the weather data extension.
language	string	Language (IETF BCP 47 language tag) in which search results should be returned by the data provider. Examples: 'en-US', 'es', 'es-MX', 'fr-FR'.
startTimeHours	integer	Start of time range. Hour 0 represents the current hour. (Only applicable for DTN.ClearAg extension.)
units	string	Units for which request to data provider is to be sent. Supported values are 'e' for English units, 'm' for Metric units, 'h' for Hybrid units (UK) and 's' for Metric SI units.
weatherDataType	string	Type of weather data (forecast/historical).

Share via

Weather Data - Get

URI Parameters

Request Header

Request Body

Responses

Security

Authorization

Examples

WeatherData_Get

Sample request

Sample response

Definitions

AdditionalProviderParameters

ApiKeyAuthCredentials

AuthCredentialsKind

Error

ErrorForLocation

ErrorResponse

InnerError

KeyVaultProperties

LocationType

Measures

Status

WeatherDataErrors

WeatherDataForPassthrough

WeatherDataProviderRequest

WeatherDataProviderResponse

WeatherLocation

WeatherLocationData

WeatherMetadata

Additional resources