Skip to content
This repository has been archived by the owner on Apr 27, 2020. It is now read-only.

Add raw-data endpoint description for MOSI #11

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add raw-data endpoint description for MOSI #11

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 122 additions & 54 deletions FORECAST-WEATHER-API-BLUEPRINT.apib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,8 @@ Here are relationship between observation periods and fields appropriately:
visibilityInMeter,weatherCode,weatherCodeTraditional,clearSkyUVIndex,uvIndexWithClouds,airTemperatureErrorInKelvin,windSpeedErrorInKnots,freezingLevelHeightInMeter,
freezingRainProbabilityInPercent,noSnowPossibleBelowHeightInMeter,snowCertainAboveHeightInMeter,saturationDeficitInHectoPascal,
airTemperatureNearGroundInCelsius,visibilityProbabilityLessThan200MeterInPercent,visibilityProbabilityLessThan1000MeterInPercent,
convectivePrecipitationProbabilityInPercent,precipitationProbabilityInPercent,precipitationType,hailProbabilityInPercent,
snowfallProbabilityInPercent,thunderstormProbabilityInPercent,condensationIndicator
convectivePrecipitationProbabilityInPercent,precipitationProbabilityInPercent,precipitationType,hailProbabilityInPercent,
snowfallProbabilityInPercent,thunderstormProbabilityInPercent,condensationIndicator
- **PT1H** - maxWindGustInMeterPerSecond,maxWindGustInKnots,maxWindGustInMilesPerHour,maxWindGustInKilometerPerHour,
sunshineDurationInMinutes,precipitationAmountInMillimeter,precipitationAmountInInch,
maxPrecipitationAmountInMillimeter,directRadiationInJoulePerSquareCentimeter,globalRadiationInJoulePerSquareCentimeter,averageGlobalRadiationInWattPerSquareMeter,relativeGlobalRadiationInPercent,
Expand All @@ -98,8 +98,8 @@ Here are relationship between observation periods and fields appropriately:
maxWindGustInMeterPerSecond,maxWindGustInKnots,maxWindGustInMilesPerHour,maxWindGustInKilometerPerHour,dominantWindDirectionInDegree,
minAirTemperatureInCelsius,minAirTemperatureInFahrenheit,minAirTemperatureInKelvin,maxAirTemperatureInCelsius,maxAirTemperatureInFahrenheit,
maxAirTemperatureInKelvin,mostLikelyLowAirTemperatureInCelsius,mostLikelyLowAirTemperatureInFahrenheit,mostLikelyLowAirTemperatureInKelvin,
minFeelsLikeTemperatureInCelsius,minFeelsLikeTemperatureInFahrenheit,minFeelsLikeTemperatureInKelvin,
maxFeelsLikeTemperatureInCelsius,maxFeelsLikeTemperatureInFahrenheit,maxFeelsLikeTemperatureInKelvin,
minFeelsLikeTemperatureInCelsius,minFeelsLikeTemperatureInFahrenheit,minFeelsLikeTemperatureInKelvin,
maxFeelsLikeTemperatureInCelsius,maxFeelsLikeTemperatureInFahrenheit,maxFeelsLikeTemperatureInKelvin,
mostLikelyHighAirTemperatureInCelsius,mostLikelyHighAirTemperatureInFahrenheit,mostLikelyHighAirTemperatureInKelvin,weatherCode,weatherCodeTraditional,
averageRelativeHumidityInPercent,averageWindSpeedInMeterPerSecond,averageWindSpeedInKnots,averageWindSpeedInMilesPerHour,averageWindSpeedInBeaufort,
averageWindSpeedInKilometerPerHour,averageAirPressureAtSeaLevelInHectoPascal,precipitationProbabilityInPercent,maxUVIndexWithClouds,minVisibilityInMeter
Expand All @@ -108,8 +108,8 @@ Here are relationship between observation periods and fields appropriately:
minAirTemperatureInCelsius,minAirTemperatureInFahrenheit,minAirTemperatureInKelvin,maxAirTemperatureInCelsius,maxAirTemperatureInFahrenheit,
maxAirTemperatureInKelvin,mostLikelyLowAirTemperatureInCelsius,mostLikelyLowAirTemperatureInFahrenheit,mostLikelyLowAirTemperatureInKelvin,
mostLikelyHighAirTemperatureInCelsius,mostLikelyHighAirTemperatureInFahrenheit,mostLikelyHighAirTemperatureInKelvin,weatherCode,weatherCodeTraditional,
minFeelsLikeTemperatureInCelsius,minFeelsLikeTemperatureInFahrenheit,minFeelsLikeTemperatureInKelvin,
maxFeelsLikeTemperatureInCelsius,maxFeelsLikeTemperatureInFahrenheit,maxFeelsLikeTemperatureInKelvin,
minFeelsLikeTemperatureInCelsius,minFeelsLikeTemperatureInFahrenheit,minFeelsLikeTemperatureInKelvin,
maxFeelsLikeTemperatureInCelsius,maxFeelsLikeTemperatureInFahrenheit,maxFeelsLikeTemperatureInKelvin,
precipitationAmountInMillimeter,precipitationAmountInInch,maxPrecipitationAmountInMillimeter,minPrecipitationAmountInMillimeter,
precipitationProbabilityMoreOrEqualThan0_1MillimeterInPercent,precipitationProbabilityMoreThan0_2MillimeterInPercent,
precipitationProbabilityMoreThan4_4MillimeterInPercent,precipitationProbabilityInPercent,
Expand All @@ -121,8 +121,8 @@ Here are relationship between observation periods and fields appropriately:
minAirTemperatureInCelsius,minAirTemperatureInFahrenheit,minAirTemperatureInKelvin,maxAirTemperatureInCelsius,maxAirTemperatureInFahrenheit,
maxAirTemperatureInKelvin,mostLikelyLowAirTemperatureInCelsius,mostLikelyLowAirTemperatureInFahrenheit,mostLikelyLowAirTemperatureInKelvin,
mostLikelyHighAirTemperatureInCelsius,mostLikelyHighAirTemperatureInFahrenheit,mostLikelyHighAirTemperatureInKelvin,weatherCode,weatherCodeTraditional,
minFeelsLikeTemperatureInCelsius,minFeelsLikeTemperatureInFahrenheit,minFeelsLikeTemperatureInKelvin,
maxFeelsLikeTemperatureInCelsius,maxFeelsLikeTemperatureInFahrenheit,maxFeelsLikeTemperatureInKelvin,
minFeelsLikeTemperatureInCelsius,minFeelsLikeTemperatureInFahrenheit,minFeelsLikeTemperatureInKelvin,
maxFeelsLikeTemperatureInCelsius,maxFeelsLikeTemperatureInFahrenheit,maxFeelsLikeTemperatureInKelvin,
convectivePrecipitationProbabilityInPercent,precipitationAmountInMillimeter,precipitationAmountInInch,
maxPrecipitationAmountInMillimeter,minPrecipitationAmountInMillimeter,precipitationProbabilityMoreOrEqualThan0_1MillimeterInPercent,
precipitationProbabilityMoreThan0_2MillimeterInPercent,precipitationProbabilityMoreThan1_4MillimeterInPercent,precipitationProbabilityMoreThan4_4MillimeterInPercent,
Expand All @@ -136,8 +136,8 @@ Here are relationship between observation periods and fields appropriately:
minAirTemperatureInCelsius,minAirTemperatureInFahrenheit,minAirTemperatureInKelvin,maxAirTemperatureInCelsius,maxAirTemperatureInFahrenheit,
maxAirTemperatureInKelvin,mostLikelyLowAirTemperatureInCelsius,mostLikelyLowAirTemperatureInFahrenheit,mostLikelyLowAirTemperatureInKelvin,
mostLikelyHighAirTemperatureInCelsius,mostLikelyHighAirTemperatureInFahrenheit,mostLikelyHighAirTemperatureInKelvin,
minFeelsLikeTemperatureInCelsius,minFeelsLikeTemperatureInFahrenheit,minFeelsLikeTemperatureInKelvin,
maxFeelsLikeTemperatureInCelsius,maxFeelsLikeTemperatureInFahrenheit,maxFeelsLikeTemperatureInKelvin,
minFeelsLikeTemperatureInCelsius,minFeelsLikeTemperatureInFahrenheit,minFeelsLikeTemperatureInKelvin,
maxFeelsLikeTemperatureInCelsius,maxFeelsLikeTemperatureInFahrenheit,maxFeelsLikeTemperatureInKelvin,
precipitationAmountInMillimeter,precipitationAmountInInch,maxPrecipitationAmountInMillimeter,minPrecipitationAmountInMillimeter,
precipitationProbabilityMoreOrEqualThan0_1MillimeterInPercent,precipitationProbabilityMoreThan0_2MillimeterInPercent,
precipitationProbabilityMoreThan4_4MillimeterInPercent,precipitationProbabilityInPercent,mostSignificantWeatherCode,mostSignificantWeatherCodeTraditional,
Expand Down Expand Up @@ -176,7 +176,7 @@ Here are relationship between observation periods and fields appropriately:
Cache-Control: max-age=90

+ Body
{
{
"forecasts": [
{
"dewPointTemperatureInCelsius": 11.9,
Expand Down Expand Up @@ -230,7 +230,7 @@ Here are relationship between observation periods and fields appropriately:
"validPeriod": "PT6H",
"precipitationProbabilityInPercent": 2
}, {
"maxAirTemperatureInFahrenheit" : 65.7,
"maxAirTemperatureInFahrenheit" : 65.7,
"weatherCode": 1,
"locatedAt": [-16.78,32.69],
"validUntil": "2016-12-13T06:00:00Z",
Expand All @@ -242,7 +242,6 @@ Here are relationship between observation periods and fields appropriately:
]
}

# Example 2:
### Forecasted weather for a given collection of *latitude* and *longitude* pairs, compressed by Point Compression Algorithm [GET]

+ Parameters
Expand All @@ -261,7 +260,7 @@ Here are relationship between observation periods and fields appropriately:
Cache-Control: max-age=90

+ Body

{
"forecasts" : [
{
Expand Down Expand Up @@ -348,7 +347,6 @@ Here are relationship between observation periods and fields appropriately:
]
}

# Example 3:
### Forecasted weather for multiple stations [GET]

+ Parameters
Expand All @@ -367,44 +365,44 @@ Here are relationship between observation periods and fields appropriately:

+ Body

{"forecasts": [
{
"sunshineDurationInMinutes": 37,
"meteoGroupStationId": "8521",
"precipitationAmountInMillimeter": 0,
"validUntil": "2016-12-13T11:00:00Z",
"maxWindGustInMeterPerSecond": 4.2,
"validFrom": "2016-12-13T10:00:00Z",
"validPeriod": "PT1H"
},
{
"sunshineDurationInMinutes": 33,
"meteoGroupStationId": "8521",
"precipitationAmountInMillimeter": 0,
"validUntil": "2016-12-13T12:00:00Z",
"maxWindGustInMeterPerSecond": 5.5,
"validFrom": "2016-12-13T11:00:00Z",
"validPeriod": "PT1H"
},
{
"sunshineDurationInMinutes": 31,
"meteoGroupStationId": "8522",
"precipitationAmountInMillimeter": 0,
"validUntil": "2016-12-13T11:00:00Z",
"maxWindGustInMeterPerSecond": 4.3,
"validFrom": "2016-12-13T10:00:00Z",
"validPeriod": "PT1H"
},
{
"sunshineDurationInMinutes": 28,
"meteoGroupStationId": "8522",
"precipitationAmountInMillimeter": 0,
"validUntil": "2016-12-13T12:00:00Z",
"maxWindGustInMeterPerSecond": 4.4,
"validFrom": "2016-12-13T11:00:00Z",
"validPeriod": "PT1H"
}
]}
{"forecasts": [
{
"sunshineDurationInMinutes": 37,
"meteoGroupStationId": "8521",
"precipitationAmountInMillimeter": 0,
"validUntil": "2016-12-13T11:00:00Z",
"maxWindGustInMeterPerSecond": 4.2,
"validFrom": "2016-12-13T10:00:00Z",
"validPeriod": "PT1H"
},
{
"sunshineDurationInMinutes": 33,
"meteoGroupStationId": "8521",
"precipitationAmountInMillimeter": 0,
"validUntil": "2016-12-13T12:00:00Z",
"maxWindGustInMeterPerSecond": 5.5,
"validFrom": "2016-12-13T11:00:00Z",
"validPeriod": "PT1H"
},
{
"sunshineDurationInMinutes": 31,
"meteoGroupStationId": "8522",
"precipitationAmountInMillimeter": 0,
"validUntil": "2016-12-13T11:00:00Z",
"maxWindGustInMeterPerSecond": 4.3,
"validFrom": "2016-12-13T10:00:00Z",
"validPeriod": "PT1H"
},
{
"sunshineDurationInMinutes": 28,
"meteoGroupStationId": "8522",
"precipitationAmountInMillimeter": 0,
"validUntil": "2016-12-13T12:00:00Z",
"maxWindGustInMeterPerSecond": 4.4,
"validFrom": "2016-12-13T11:00:00Z",
"validPeriod": "PT1H"
}
]}

# Group Aggregations by polygon

Expand All @@ -415,6 +413,7 @@ A LinearRing is closed LineString with 4 or more positions. The first and last p
Though a LinearRing is not explicitly represented as a GeoJSON geometry type, it is referred to in the Polygon geometry type definition.
More information is here: https://geojson.org/geojson-spec.html#polygon

## Get aggregated value by polygon [GET /aggregate{?locatedWithin}{?validFrom}{?validUntil}{?validPeriods}{?fields}]
#### Example - Get maxThunderstormProbabilityInPercent for PT0S period
'https://point-forecast.weather.mg/aggregate?locatedWithin={%22type%22:%22Polygon%22,%22coordinates%22:[[[12,5],[14,531],[13,52.9],[12,5]]]}&validPeriod=PT0S&fields=maxThunderstormProbabilityInPercent&validFrom=2017-08-05T00:00:00Z&validUntil=2017-08-05T03:00:00Z'

Expand All @@ -432,7 +431,7 @@ More information is here: https://geojson.org/geojson-spec.html#polygon
Cache-Control: max-age=90

+ Body
{
{
"forecasts": [
{
"locatedWithin": {
Expand Down Expand Up @@ -553,6 +552,75 @@ More information is here: https://geojson.org/geojson-spec.html#polygon
]
}

# Group Raw data access

Having special permissions client may separately request original and edited forecast data.
By given station id, timespan and additional filters raw data will be returned. Note that format of this raw data is different from regular forecast. There is no aggregation, calculated fields, periods in raw data. See example below.

Fields available for querying are listed below. Most of these fields have a counterpart in [parameters spreadsheet](http://tinyurl.com/mgweatherapi).
+ stationId - MeteoGroup station identifier
+ stationLocation - station location
+ forecastAt - timestamp when this forecast is valid
+ forecastIssuedAt - forecast issue timestamp
+ source - origin forecast file name
+ meteobaseChanges - if raw forecast represents original or edited values
+ weatherCode fields:
+ weatherCode, regionalWeatherCode, weatherCodePast3Hours, weatherCodePast6Hours, weatherCodeMostSignificantPast12Hours, weatherCodePast12Hours, weatherCodeMostSignificantPast24Hours
+ temperature fields:
+ temperatureInCelsius, temperatureMaxInCelsius, temperatureMinInCelsius, temperature10CmAboveGrassInCelsius, temperatureMin10CmAboveGrassInCelsius, dewPointTemperatureInCelsius, temperaturePast24HourInCelsius
+ relativeHumidityInPercent
+ wind fields:
+ windDirectionInDegree, windSpeedInKnot, errorInWindSpeedInKnot, windSpeedMaxMeanPast1HourInKnot, windGustMaxPast1HourInKnot, windGustProbabilityGreaterThan40KnotsPast1HourInPercent, windGustMaxPast3HoursInKnot, windSpeedMaxPast6HoursInKnot, windGustMaxPast6HoursInKnot
+ precipitation fields:
+ precipitationTypeInCode, precipitationTypeMostSignificantPast24HoursInCode, precipitationPast1HourInMillimeter, precipitationMaxPast1HourInMillimeter, precipitationPast6HoursInMillimeter, precipitationMinPer6HoursInMillimeter, precipitationMaxPer6HoursInMillimeter, precipitationPer12HoursInMillimeter, precipitationMinPer12HoursInMillimeter, precipitationMaxPer12HoursInMillimeter, precipitationPer24HoursInMillimeter, precipitationMax24HoursInMillimeter, precipitationMin24HoursInMillimeter, precipitationDurationPast6HoursInHours
+ precipitation probability fields:
+ precipitationProbabilityHoursMoreOrEqualThan0_1MillimetersPast24InPercent, precipitationProbabilityMoreThan0_2MillimetersPast24HoursInPercent, precipitationProbabilityMoreThan4_4MillimetersPast24HoursInPercent, precipitationForMediaCustomersProbabilityInPercent, precipitationProbabilityMoreOrEqualThan0_1MillimeterPast12HoursInPercent, precipitationProbabilityMoreThan0_2MillimetersPast12HoursInPercent, precipitationProbabilityMoreThan1_4MillimetersPast12HoursInPercent, precipitationProbabilityMoreThan4_4MillimetersPast12HoursInPercent, precipitationProbabilityMoreThan20MillimetersPast12HoursInPercent, precipitationProbabilityMoreOrEqualThan0_1Past6HoursInPercent, precipitationProbabilityMoreThan0_2MillimetersPast6HoursInPercent, precipitationProbabilityMoreThan4_4MillimetersPast6HoursInPercent, convectivePrecipitationProbabilityInPercent, convectivePrecipitationProbabilityPast12HoursInPercent, precipitationProbabilityInPercent
+ significant weather fields:
+ thunderstormProbabilityInPercent, thunderstormProbabilityPast12HoursInPercent, freezingRainProbabilityPast12HoursInPercent, freezingRainProbabilityInPercent, hailProbabilityPast12HoursInPercent, hailProbabilityInPercent, groundFrostProbabilityPast12HoursInPercent, freezingLevelHeightInMeter
+ visibility fields:
+ visibilityInMeters, visibilityprobabilityLessThan1000MetersInPercent, visibilityProbabilityLessThan200MetersInPercent
+ cloud cover fields:
+ cloudCoverTotalInOcta, cloudCoverEffectiveInOcta, cloudCoverEffectivePast12HoursInOcta, cloudCoverLowerThan5000MetersInOcta, cloudCoverLowerThan2000MetersInOcta, cloudCoverEffectivePast6HoursInOcta, cloudBaseHeightInMeter, clearSkyUVIndex
+ snow fields:
+ noSnowPossibleHeightInMeters, snowfallFreshPast1HourInCentimeter, snowfallFreshMaxPast1HourInCentimeter, snowProbabilityInPercent, snowfallFreshPast6HoursInCentimeter, snowfallFreshMaxPast6HoursInCentimeter, snowCertainHeightInMeter, snowProbabilityPast12HoursInPercent
+ radiation fields:
+ directRadiationPast1HourInJoulePerCentimeterSquare, globalRadiationPast1HourInJoulePerCentimeterSquare, globalRadiationPast24HoursInJoulPerCentimeterSquare, globalRadiationRelativePast1HourInPercent
+ pressureAtSeaLevelInHektoPascal - air pressure
+ sunshine fields:
+ sunshineDurationRelativePast1HourInPercent, sunshineDurationPast24HoursInHours, sunshineDurationRelativePast24HoursInPercent, saturationDeficitInHektoPascal, saturationDeficitPast24HoursInHektoPascal, evaporationMakkinkPast24HoursInMillimeter, evaporationPenmanPast24HoursInMillimeter

## Access raw data [GET /raw-data{?meteoGroupStationIds}{?validFrom}{?validUntil}{?fields}{?meteobaseChanges}]

+ Parameters
+ meteoGroupStationIds: `6510737` (string, required) - comma separated list of station ids that provide forecast.
+ validFrom: `2018-08-09T12:00:00Z` (string, required) - ISO8601 timestamp notation of start time (inclusive).
+ validUntil: `2018-08-09T13:00:00Z` (string, required) - ISO8601 timestamp notation of end time (inclusive).
+ fields: `temperatureInCelsius,meteobaseChanges` (string, required) - comma separated list of parameters in the response.
+ meteobaseChanges: `true` (boolean, optional) - whether filtering by edited flag is necessary. If not specified, both edited and original values are returned.

+ Response 200 (application/json)
+ Body

```
[
{
"stationId": "6510737",
"forecastAt": "2018-08-09T12:00:00Z",
"forecastIssuedAt": "2018-08-09T06:36:00.000Z",
"documentIngestedAt": "2018-08-09T06:06:37.427Z",
"meteobaseChanges": true,
"temperatureInCelsius": 31.4
},
{
"stationId": "6510737",
"forecastAt": "2018-08-09T13:00:00Z",
"forecastIssuedAt": "2018-08-09T06:49:00.000Z",
"documentIngestedAt": "2018-08-09T06:49:44.193Z",
"meteobaseChanges": true,
"temperatureInCelsius": 30.6
}
]
```

# Data Structures

Expand Down