This repository has been archived by the owner on Apr 27, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathLIGHTNING-API-BLUEPRINT.apib
227 lines (169 loc) · 10.4 KB
/
LIGHTNING-API-BLUEPRINT.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
FORMAT: 1A
Weather API
=============================
# General information
This technical document was created for developers who are creating applications based on weather data provided by this API.
This document is using [API blueprint format](https://apiblueprint.org/documentation/).
### Authentication
To access active-warning-service the request has to be authorised with a valid
JWT OAuth 2.0 access token, obtained from the DTN Authorisation server
`https://auth.weather.mg/oauth/token` with according client credentials. The
required scope is `lightning`.
The documentation about how to authenticate against DTN
Weather API with
OAuth 2.0 can be found here: [Weather API documentation](https://github.com/MeteoGroup/weather-api/blob/master/authorization/Authentication.md)
#### Client Credentials
Before getting an access to any endpoints, need to obtain **client id** and **client secret**.
For achieving this, please use [request form](https://meteogroup.zendesk.com/hc/en-gb/requests/new?ticket_form_id=64951).
#### Authorization Token
Once you have your client credentials (Client-ID + Password), you can request a token on
[Authorization server](https://auth.weather.mg/oauth/token?grant_type=client_credentials with http basic auth).
The token will be in the return message, encrypted with a key from the authorization service.
It will contain the client-ID, scopes and expiration date.
The token is only a valid for a limited time, after this it will expired and you have to request a new token again.
#### Using Authorization Token
HTTP GET request to the endpoints needs to provide Authorization Token into **Authorization** HTTP Header.
More information about JWT token might be found here: https://en.wikipedia.org/wiki/JSON_Web_Token.
HTTP Header: **Authorization** : **Bearer {ENCRYPTED TOKEN HERE}**
The Authorization token contains the Scopes which the client is allowed to have.
**lightning** is the scope which allows to request Lightning Service.
### Backward compatibility
Every endpoint may add one or more response parameters in the future.
Clients should ignore unknown parameters, to avoid technical issues.
# Group Lightning
## Retrieve lightning observation [?provider={provider1,provider2}&locationWithin={lonTopLeft,latTopLeft,lonBottomRight,latBottomRight}&occurredFrom={startTime}&occurredUntil={endTime}&startPosition={startPosition}]
## Retrieve lightning observation [?provider={provider1,provider2}&locationWithin={lonTopLeft,latTopLeft,lonBottomRight,latBottomRight}&occurredFrom={startTime}]
#### Example
https://lightning.weather.mg/search?provider=NOWCAST&locationWithin=[-10,80],[10,5]&occurredFrom=2017-01-05T12:21:14Z&occurredUntil=2017-01-05T12:21:15Z&startPosition=30000
https://lightning.weather.mg/search?provider=NOWCAST&locationWithin=[-10,80],[10,5]&occurredFrom=2017-01-05T12:21:14Z
https://lightning.weather.mg/search?provider=NOWCAST&locationWithin=[-10,80],[10,5]
##### Limitation
Due to some technical constraints, the response payload size is limited to max. 6MB - this is equivalent to ca. 30000 lightning events. If there are more than 30000 results in storage which comply to the search criteria, they can be retrieved using pagination.
In such case the response payload contains [HAL](http://stateless.co/hal_specification.html)-compatible `_link` object which contains links to the next page and the response type is application/hal+json.
If locationWithin is worldwide [-180, 90][180, -90] and occurrence ~3 days
### Observed lightning for a given boundingBox and time period
This resource provides data from existing lightning observation providers.
For any request service returns a set of lightnings occurred in geographical
bounding box locations during period of time specified in parameters.
+ Parameters
+ locationWithin: `[-10,80],[10,5]` (longitude top left,
latitude top left,
longitude bottom right,
latitude bottom_right, required)
- longitude in degree numeric format and in range <-180,180> eg. -123.454, 179.864
- latitude in degree numeric format and in range <-90,90> eg. -85.541, 5.32,
+ occurredFrom: `2017-01-05T12:21:14Z` (start time range, optional)
- start lightning observation time. End time is current time by default, setup by the service.
+ occurredUntil: `2017-01-05T12:21:15Z` (end time range, optional)
- time range period for lightning observation.
+ provider: `ENTLN,NOWCAST` (string, required)
- lightning providers.
+ startPosition: `60000` (not negative integer, optional)
- Is used for pagination. It is recommnded to set it as multiple of 30 000.
+ Response 200 (application/hal+json)
+ Headers
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.EkN-DOsnsuRjRO6BxXemmJDm3HbxrbRzXglbN2S4sOkopdU4IsDxTI8jO19W_A4K8ZPJijNLis4EZsHeY559a4DFOd50_OqgHGuERTqYZyuhtF39yxJPAjUESwxk2J5k_4zM3O-vtd1Ghyo4IbqKKSy6J9mTniYJPenn5-HIirE
+ Body
{
"lightnings":[
{
"occurredAt":"2017-01-05T12:21:14.974Z",
"provider":"NOWCAST",
"lightningType":"CLOUD_TO_GROUND",
"elevationInKilometers":0,
"currentInAmpere":4500,
"location":[
9.6345,
19.3064
]
},
{
"occurredAt":"2017-01-05T12:21:14.974Z",
"provider":"ENTLN",
"lightningType":"CLOUD_TO_GROUND",
"elevationInKilometers":0,
"currentInAmpere":4700,
"location":[
8.6345,
20.3064
]
},
{
"provider": "NOWCAST",
"occurredAt": "2017-01-05T12:20:14.974Z",
"elevationInKilometers": 0,
"lightningType": "CLOUD_TO_GROUND",
"currentInAmpere": -3500,
"location": [
9.3345,
19.7064
]
}
],
"lightningsTotal": 164256,
"lightningsInResponse": 30000,
"_links": {
"self": {
"href": "https://lightning.weather.mg/search?provider=ENTLN&startPosition=60000&locationWithin=[-180,90],[180,-90]"
},
"next": {
"href": "https://lightning.weather.mg/search?provider=ENTLN&startPosition=90000&locationWithin=[-180,90],[180,-90]"
}
}
}
#
# Weighted Lightning
## Retrieve weighted lightning observation [?temporalResolution={temporalResolution}&spatialResolution={resolution}&locationWithin={lonTopLeft,latTopLeft,lonBottomRight,latBottomRight}&occurredFrom={startTime}&occurredUntil={endTime}]
## Retrieve weighted lightning observation [?temporalResolution={temporalResolution}&spatialResolution={resolution}&locationWithin={lonTopLeft,latTopLeft,lonBottomRight,latBottomRight}&occurredFrom={startTime}]
#### Example
https://lightning.weather.mg/weighted?&temporalResolution=PT15M&spatialResolution=0.5&locationWithin=[-10,80],[10,5]&occurredFrom=2017-01-05T12:19:14Z&occurredUntil=2017-01-05T12:21:15Z
https://lightning.weather.mg/weighted?&temporalResolution=PT15M&spatialResolution=0.5&locationWithin=[-10,80],[10,5]&occurredFrom=2017-01-05T12:19:14Z
https://lightning.weather.mg/weighted?&temporalResolution=PT15M&spatialResolution=0.5&locationWithin=[-10,80],[10,5]
### Observed weighted lightning for a given boundingBox, time period, weighted by time span and spatial resolution
This resource provides data from existing lightning observation providers: NOWCAST and ENTLN.
For any request service returns a set of lightnings occurred in geographical
bounding box locations during period of time specified in parameters.
-##### Limitation
- Due to thenchnical reasons, the maximum allowed response time is 30 seconds and it is possible to process lightning events in a batch of 200 000 lightnings only.
+ Parameters
+ temporalResolution: 'PT15M, PT5M, PT1M' in minutes(string required)
- time span interval in which lightning should be weighted
+ spatialResolution '0.5, 0.25, 0.05' degree(string required)
- spatial resolution within which lightning should be weighted
+ locationWithin: `[-10,80],[10,5]` (longitude top left,
latitude top left,
longitude bottom right,
latitude bottom_right, required)
- longitude in degree numeric format and in range <-180,180> eg. -123.454, 179.864
- latitude in degree numeric format and in range <-90,90> eg. -85.541, 5.32,
+ occurredFrom: `2017-01-05T12:21:14Z` (start time range, optional)
- start lightning observation time. End time is current time by default, setup by the service.
+ occurredUntil: `2017-01-05T12:21:15Z` (end time range, optional)
- time range period for lightning observation.
+ Response 200 (application/json)
+ Headers
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.EkN-DOsnsuRjRO6BxXemmJDm3HbxrbRzXglbN2S4sOkopdU4IsDxTI8jO19W_A4K8ZPJijNLis4EZsHeY559a4DFOd50_OqgHGuERTqYZyuhtF39yxJPAjUESwxk2J5k_4zM3O-vtd1Ghyo4IbqKKSy6J9mTniYJPenn5-HIirE
+ Body
{
"weightedLightnings": [{
"occurredFrom": "2017-01-05T12:15:00.000Z",
"occurredUntil": "2017-01-05T12:30:00.000Z",
"totalCurrentInAmpere": 8000,
"weightedLocation": [9.5033, 19.4814],
"numberOfLightnings": 2,
"temporalResolution": "PT15M",
"region": [[9.25, 19.75], [9.75, 19.25]],
"weightedOccurrence": "2017-01-05T12:20:47.000Z"
}, {
"occurredFrom": "2017-01-05T12:15:00.000Z",
"occurredUntil": "2017-01-05T12:30:00.000Z",
"totalCurrentInAmpere": 4700,
"weightedLocation": [8.6345, 20.3064],
"numberOfLightnings": 1,
"temporalResolution": "PT15M",
"region": [[8.25, 20.75], [8.75, 20.25]],
"weightedOccurrence": "2017-01-05T12:21:14.000Z"
}
]
}
#