diff --git a/FORECAST-WEATHER-API-BLUEPRINT.apib b/FORECAST-WEATHER-API-BLUEPRINT.apib index 611afed..5124569 100644 --- a/FORECAST-WEATHER-API-BLUEPRINT.apib +++ b/FORECAST-WEATHER-API-BLUEPRINT.apib @@ -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, @@ -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 @@ -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, @@ -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, @@ -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, @@ -176,7 +176,7 @@ Here are relationship between observation periods and fields appropriately: Cache-Control: max-age=90 + Body - { + { "forecasts": [ { "dewPointTemperatureInCelsius": 11.9, @@ -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", @@ -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 @@ -261,7 +260,7 @@ Here are relationship between observation periods and fields appropriately: Cache-Control: max-age=90 + Body - + { "forecasts" : [ { @@ -348,7 +347,6 @@ Here are relationship between observation periods and fields appropriately: ] } -# Example 3: ### Forecasted weather for multiple stations [GET] + Parameters @@ -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 @@ -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' @@ -432,7 +431,7 @@ More information is here: https://geojson.org/geojson-spec.html#polygon Cache-Control: max-age=90 + Body - { + { "forecasts": [ { "locatedWithin": { @@ -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