GeoPressureAPI is a JSON API that makes it easy to compute the mismatch of a geolocator pressure timeserie with the atmospheric pressure from ERA5-LAND reanalysis data.
This docs describe how to use the GeoPressure API. We hope you enjoy these docs, and please don't hesitate to file an issue if you see anything missing.
POST /glp.mgravey.com/GeoPressure/v2/map/With this end-point, you will be able to compute the maps of pressure mismatch from a geolocator pressure timeseries.
The input parameters are the labeled pressure timeseries (time, pressure, label) and the grid (West, South, East, North, scale). See below for details.
We return a geotiff map with one or two layers.
- mse: The first layer is the mismatch between the input pressure timeseries and the reanalysis one at each location. This is computed with a mean square error (MSE) where the mean error is removed. The mean error is removed because we assume no specific altitude of the geolocator, thus allowing an altitudinal shift of the pressure timeseries.
- mask: (optional) The second layer quantifies how often the pressure timeseries corresponds to altitude falling within the min and max ground elevation found in each pixel of the map. For instance, a pixel with a value of 0.9 indicates that for 90% of the timeseries, the bird was found on an elevation which exists in the range of altitude found in that pixel. The altitude value of the geolocator pressure timeseries is computed with the barometric formula accounting for the temporal variation of pressure (surface-pressure) and temperature (2m-temperature) based on ERA5 data. The min and max ground elevation of each pixel is computed from SRTM-90. In addition, you can use the
marginparameter to account for possible errors in pressure and vertical movement of the bird. It define a range of pressure error acceptable where the bird is still considered to be on the ground. You can not return this layer using theincludeMaskparamaters.
In order to save computational time, you can use the maskThreshold parameter which will filter the mask layer and only keep pixel with a mask value above the threashold for the rest of the computation. This means that the mse layer is only computed for these pixels.
To get these maps, you first need to call the API which will return a list of urls (one for each unique label). Then, using these urls, you can download the geotiff of the output map. Note that the actual calculation is only performed when you request the map (second step), making this step much longer.
The time range available to query is the same as ERA5-Land data, which is from 1981 to three months from real-time. More information can be found at the Copernicus Climate Data Store and the the corresponding Google Earth Engine dataset.
The time resolution of the ERA5-Land is 1 hours. The API will compute the match for any timestamp provided in the request by using the closest 1 hours. To avoid redundant information, downscale the timeseries to 1 hour before the request.
| Parameter | Type | Description |
|---|---|---|
W |
number |
Required. West coordinate. -180° to 180°. |
S |
number |
Required. South coordinate. 0° to 90°. |
E |
number |
Required. East coordinate. -180° to 180°. |
N |
number |
Required. North coordinate. 0° to 90°. |
scale |
number |
default: 10. Number of pixels per latitude, longitude. 10 for a resolution of 0.1° (~10) and 4 for a resolution of 0.25° (~30km). To avoid interpolating the ERA5 data, scale should be smaller than 10. Read more about scale on Google earth Engine documention.. |
pressure |
array of number |
Required. Atmospheric pressure to match in Pascal. |
time |
array of number |
Required. UNIX time of the pressure data (i.e., number of second since 1-janv-1970. |
label |
array of string/number |
Required. Define the grouping of the pressure data. All pressure with the same label will be match together |
maxSample |
number |
default: 250. The computation of the mismatch is only performed on maxSample datapoints of pressure to reduce computational time. The samples are randomly (uniformly) selected on the timeseries. |
margin |
number |
default: 30. The margin is used in the threshold map to accept some measurement error. unit in meter. (1hPa~10m) |
includeMask |
boolean |
default: true. Specify if the mask variable should be included in the download. If set to false, only the MSE band will be downloaded. |
maskThreshold |
float |
default: 0. A value above 0 will filter the map to only compute the MSE at pixel where the proportion of pressure datapoint are falling at ground level. Typically a value of 0.9 can considerably reduce the computational time by only considering pixel above this threashold. |
See example for response structure.
| Parameter | Type | Description |
|---|---|---|
status |
success or error |
|
taskId |
number |
Task ID. Use this ID for communication if you have any problem. |
labels |
array of string/number |
List of unique labels. Same order than urls. |
urls |
array of string |
List of the mismatch urls. |
resolution |
number |
resolution in degree. Same resolution for latitude and longitude. |
size |
array of number |
Number of pixel of the map. |
bbox |
Object |
Bounding box requested. |
includeMask |
boolean |
The boolean flag indicating if the mask variable was included. |
maskThreshold |
float |
The threshold value used to generate the mask. |
errorMesage |
string |
In case status==error, errorMessage provides the reason for the error |
advice |
string |
In case status==error, advice provides guidance on how to solve the problem |
Each url will with return a geotiff file with one or two bands/layers: mse and optionally the mask. Pixels not covered by the data (i.e., water) are indecated with a value of -2, while pixels with a mse below maskThreashold are indicated with a -1 in the mse.
POST /glp.mgravey.com/GeoPressure/v2/map/{
"W": -18,
"S": 4,
"E": 16,
"N": 51,
"time": [1572075000,1572076800,1572078600],
"pressure": [97766,97800,97833],
"label": [1,1,1]
}{
"status" : success,
"task_id" : 1639259414,
"data" : {
"labels": [1],
"urls": ['https://earthengine.googleapis.com/v1alpha/projects/earthengine-legacy/thumbnails/d0f8335cac1ccb4bb27da95ecf7d5718-65cde402d14f88a8a7fcf8256c8793e5:getPixels'],
"resolution": 0.25,
"size": [136 188],
"bbox": {w:-18, S:4, E:16, N:51},
"time2GetUrls": 11.61416506767273,
"includeMask": true,
"maskThreshold": 0.9,
}
}POST /glp.mgravey.com/GeoPressure/v2/timeseries/The second endpoint allows you to return the pressure timeseries at one specific location. This can be useful to check visually the match of the geolocator pressure with the ERA5 pressure at a specific location (e.g., most likely position according to the response of the endpoint map).
If you supply the pressure (and time) of the geolocator, it will additionally return the altitude of the geolocator (above sea level).
The timeseries of the response will be the same as time if supply, otherwise, it will return on an hourly basis between startTime and endTime.
When requesting a position on water, it will move the position to the shortest point on land. The response will include distInter >0 and the exact coordinates used in the computation.
| Parameter | Type | Description |
|---|---|---|
lon |
number |
Required. longitude coordinate. -180° to 180°. |
lat |
number |
Required. latitude coordinate. 0° to 90°. |
pressure |
array of number |
geolocator pressure. |
time |
array of number |
Required if pressure. UNIX time of the pressure data (i.e., number of second since 1-janv-1970. |
startTime |
number |
Required if NOT pressure. UNIX time of start (i.e., number of second since 1-janv-1970. |
endTime |
number |
Required if NOT pressure. UNIX time of end (i.e., number of second since 1-janv-1970. |
See example for response structure.
| Parameter | Type | Description |
|---|---|---|
status |
success or error |
|
taskId |
number |
Task ID. Use this ID for communication if you have any problem. |
url |
string |
urls of the response timeseries |
distInter |
number |
Distance interpolated from the requested coordinate to the one used. meters. |
lon |
number |
longitude coordinate used (different than requested if over water). |
lat |
number |
latitude coordinate used (different than requested if over water). |
The url will with return a csv the following columns:
| time | pressure | (altitude) |
|---|---|---|
| ... | ... | ... |
POST /glp.mgravey.com:24853/GeoPressure/v2/timeseries/{
"lon": 6,
"lat": 46,
"startTime": 1497916800,
"endTime": 1500667800
}{
"status" : success,
"task_id" : 1639259414,
"data" : {
urls: ['https://earthengine.googleapis.com/v1alpha/projects/earthengine-legacy/thumbnails/d0f8335cac1ccb4bb27da95ecf7d5718-65cde402d14f88a8a7fcf8256c8793e5:getPixels'],
format: 'csv'
}
}POST /glp.mgravey.com/GeoPressure/v2/elevationPath/This entry point returns the ground elevation from SRTM (SRTM90_V4) along a polyline
| Parameter | Type | Description |
|---|---|---|
lon |
array of number |
Required. longitude coordinate. -180° to 180°. |
lat |
array of number |
Required. latitude coordinate. 0° to 90°. |
scale |
number |
Required. Number of pixels per latitude, longitude. 10 for a resolution of 0.1° (~10) and 4 for a resolution of 0.25° (~30km). Read more about scale on Google earth Engine documention.. |
samplingScale |
number |
Required. Number of pixels per latitude, longitude. 10 for a resolution of 0.1° (~10) and 4 for a resolution of 0.25° (~30km). To avoid interpolating the ERA5 data, scale should be smaller than 10. Read more about scale on Google earth Engine documention.. |
percentile |
array of number |
Required Between 0 and 100. |
POST /glp.mgravey.com:24853/GeoPressure/v2/timeseries/{
"lon": [8.47, 9.41, 9.01, -0.91, 14.24, 27.30, 34.39, 30.00],
"lat": [48.89, 44.78, 40.07, 37.68, 17.33, 7.32, 8.09, -23.13],
"scale": 10
"smaplingScale": 1
}{
"status" : "success",
"task_id" : 1639259414,
"data" : {
"percentileData": {
"10": [0, 0, 0, 0, 305, 357, 289, 426, 399, 402, 209, 119, 0, 0],
"50": [237, 237, 237, 587, 552, 551, 363, 569, 553, 981, 1137, 545, 188, 188],
"90": [880, 880, 880, 1260, 1138, 859, 480, 900, 756, 1788, 1768, 1311, 1002, 1002],
"distance": [0, 462486, 986718, 1886940, 2997967.759714002, 4107611.1789356107, 4585219, 5696169.77351964, 6384645, 7171428, 8277490.328782117, 9383674.502677774, 10490621.943273364, 10657884],
"lat": [44.927, 44.927, 44.927, 34.943, 24.959, 24.959, 14.976, 14.976, 4.992, 4.992, -4.992, -14.976, -24.959, -24.959],
"lon": [4.992, 4.992, 4.992, -4.992, 4.992, 14.976, 14.976, 24.959, 24.959, 34.943, 34.943, 34.943, 34.943, 34.943],
"stapId": [0, 1, 2, 3, 3.4117541918601204, 3.8229953380328396, 4, 4.61739187333294, 5, 6, 6.317245494740039, 6.634525937613036, 6.952025303882606, 7]
},
"scale": 1111390.0,
"samplingScale": 1111390.0,
"percentile": [10, 50, 90]
}
}To install the server:
- Clone this repository.
git clone https://github.com/Rafnuss/GeoPressureAPI- Add the
jsonfile with the key in the repository. - Update
bootServer.shwith the appropriate service address. - Create a
logsfolder - Add a route to the server if needed
sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 80
sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 443- Run the server
bash bootServer.sh