Introduction
Welcome to the Skydipper API Documentation.
Authentication
The Skydipper API uses JWT (JSON Web Tokens) to identify and authenticate its users. This token must be provided inside an Authorization header, with the form Bearer: <token>.
However, in order to perform GET requests for content that is not private, there’s no need for any sort of authentication or token.
How to create a new user
To create a new user make a request like the one in the sidebar:
curl -X POST https://api.skydipper.com/auth/user \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"email":"<email>",
"role":"<role>",
"extraUserData": {
"apps": [
"<apps>"
]
}
}'
There are three allowed roles: USER, MANAGER and ADMIN. The ‘apps’ field only permits applications that are powered by the API: for now the only application is skydipper, but some more will be available in the future.
How to generate your private token
Endpoint for email + password based login.
# Email + password based login - JSON format
curl -X POST http://api.skydipper.com/auth/login \
-H "Content-Type: application/json" -d \
'{
"email":"your-email@provider.com",
"password":"potato"
}'
Refer to user management for more information on the operations available in the Skydipper API for managing user accounts, token generation, etc.
Basemaps
The Basemap microservice serves pre-calculated and dynamic tiles for Layer objects and several pre-built styles. The code for this service can be found here.
Annual Landsat Basemaps
We have created satellite basemaps based off of the NASA/USGS Landsat satellite collection. These are avaiable as slippy map tiles.
We are continuing to add years of coverage to our Landsat Basemap collection. The collection we have currently processed
is avaiable via https://api.skydipper.com/v1/landsat/<year>/<z>/<x>/<y>.
The service mixes pre-cached and dynamic tiles. The dynamic tiles kick-in at z>11.
import requests
url = "http://api.skydipper.com/v1/basemaps/landsat/2016/14/8473/7643"
r = requests.get(url)
print(r.status_code)
with open('./image_test.jpg', 'wb') as handler:
handler.write(r.content)
Layer Basemaps
Appropriate layers in Skydipper (i.e. geospatial data, with either the EE or CartoDB provider and visulisation properties)
can be visulised as map tiles by calling https://api.skydipper.com/v1/basemaps/layer/<layer_id>/<z>/<x>/<y>.
import requests
url = "http://api.skydipper.com/v1/basemaps/layer/e7070d5f-3d38-46b1-86eb-e98782da55dd/14/8473/7643"
r = requests.get(url)
print(r.status_code)
with open('./image_test.jpg', 'wb') as handler:
handler.write(r.content)
Movie tiles
Coming soon.
Composite Imagery
The Composite service enables the creation of on-the-fly composites based on either Landsat-8, or Sentinel-2 and a Geostore geometry ID. Composites can be returned in a variety of formats, either as url links to thumbnail and slippy map (z/x/y) tile assets, or as a zip folder containing image assets.
Band visulisations can be given as argument to visulise any bands of interest in RGB space.
Digital Elevation Model (DEM) image assets can also be returned with the get_dem=True flag.
Code for the Composite service is hosted on Github.
Thumbnails and slippy maps
By default, the service accepts a Gestore id hash as an argument via the geostore param in a GET request.
The response is JSON containing urls (with tokens valid for 2 days), linking to Z/X/Y type (slippy) maps, as well as
a thumbnail, and a greyscale Digital Elevation Model (DEM) output (if get_dem is set to True).
params = {"geostore": "<geostore_id>",
"get_dem": True,
"date_range": "[2018-01-01, 2018-12-01]",
"thumb_size": "[500, 500]",
"instrument": "landsat",
"cloudscore_thresh": 5,
"band_vizz": "{'bands': ['B4', 'B3', 'B2'], 'min': 0, 'max': 0.4}",
"get_files": False}
r = requests.get(f"https://api.skydipper.com/v1/composite-service", params=params)
print(r.json())
Response
{
"attributes": {"dem": "https://earthengine.googleapis.com/api/thumb?thumbid=6162ac5f8444eed070b537732711b688&token=XXXX",
"thumb_url": "https://earthengine.googleapis.com/api/thumb?thumbid=580652e722a7660ab7137ffb21ce664e&token=XXXXX",
"tile_url": "https://earthengine.googleapis.com/map/1eaa150375fa8c9b1e00aa78f754f9d1/{z}/{x}/{y}?token=XXXXX",
"zonal_stats": "None"},
"id": "None",
"type": "composite_service"
}
Downloading Image Assets
Sometimes you want more than a thumnail and web map tiles. If you want to build 3D models with these assets you will
need to download the composite as a surface texture and apply that texture to a surface (ideally using the DEM
to deform the surface to show height also). To do this you will need to hit the service with get_files=True, and then
unzip the assets folder that is returned in the response.
params = {"geostore": "<geostore_id>",
"get_dem": True,
"date_range": "[2019-01-01, 2019-12-01]",
"thumb_size": "[250, 250]",
"instrument": "landsat",
"get_files": True}
r = requests.get(f"https://api.skydipper.com/v1/composite-service", params=params)
print(r.json())
Dataset
What is a Dataset?
A dataset abstracts the data that can be obtained from several sources into a common interface. There are several data providers supported in the API, and each of those has a different provider. Datasets can belong to several applications.
Supported dataset sources
Third party Dataset connectors
For data stored on third party services.
Carto
(connectorType: 'rest', provider: 'cartodb')
CARTO is an open, powerful, and intuitive map platform for discovering and predicting the key insights underlying the location data in our world.
ArcGIS Feature service
(connectorType: 'rest', provider: 'featureservice')
ArcGIS for server is a Complete, Cloud-Based Mapping Platform.
Google Earth Engine
(connectorType: 'rest', provider: 'gee')
Google Earth Engine combines a multi-petabyte catalog of satellite imagery and geospatial datasets with planetary-scale analysis capabilities and makes it available for scientists, researchers, and developers to detect changes, map trends, and quantify differences on the Earth’s surface.
Getting all datasets
This endpoint will allow to get all datasets available in the API:
curl -X GET https://api.skydipper.com/v1/dataset
Response:
{
"data": [
{
"id": "098b33df-6871-4e53-a5ff-b56a7d989f9a",
"type": "dataset",
"attributes": {
"name": "Subnational Political Boundaries",
"slug": "Politcial-Boundaries-GADM-adminitrative-level-1-1490086842541",
"type": "tabular",
"subtitle": "GADM",
"application": ["skydipper"],
"dataPath": null,
"attributesPath": null,
"connectorType": "rest",
"provider": "cartodb",
"userId": "57a0aa1071e394dd32ffe137",
"connectorUrl": "https://wri-01.carto.com/tables/gadm28_adm1/public",
"tableName": "gadm28_adm1",
"status": "saved",
"published": true,
"overwrite": false,
"verified": false,
"blockchain": null,
"subscribable": null,
"mainDateField": null,
"env": "production",
"geoInfo": true,
"protected": true,
"legend": {
"date": [],
"region": [],
"country": [],
"nested": []
},
"clonedHost": null,
"errorMessage": null,
"taskId": null,
"updatedAt": "2018-11-21T13:54:56.285Z",
"dataLastUpdated": null
}
},
...
],
"links": {
"self": "http://api.skydipper.com/v1/dataset?page[number]=1&page[size]=10",
"first": "http://api.skydipper.com/v1/dataset?page[number]=1&page[size]=10",
"last": "http://api.skydipper.com/v1/dataset?page[number]=99&page[size]=10",
"prev": "http://api.skydipper.com/v1/dataset?page[number]=1&page[size]=10",
"next": "http://api.skydipper.com/v1/dataset?page[number]=2&page[size]=10"
},
"meta": {
"total-pages": 99,
"total-items": 990,
"size": 10
}
}
Slug & dataset-id
Datasets have an auto-generated and unique slug and id that allows the user to get, create, update, query or clone that dataset.
The dataset slug and the id cannot be updated even if the name changes.
Error Message
When a dataset is created the status is set to “pending” by default. Once the adapter validates the dataset, the status is changed to “saved”. If the validation fails, the status will be set to “failed” and the adapter will also set an error message indicating the reason.
Filters
The dataset list provided by the endpoint can be filtered with the following attributes:
| Filter | Description | Accepted values |
|---|---|---|
| name | Allow us to filter by name | any valid text |
| type | Allow us to distinguish between tabular and raster datasets | raster or tabular |
| app | Aplications to which this dataset is being used | Available Aplications like: ["skydipper"] |
| connectorType | rest (placeholder for future connectors not based in rest) |
|
| provider | Dataset provider this include inner connectors and 3rd party ones | A valid dataset provider |
| userId | the user who registered the dataset | valid id |
| status | the internal dataset status at connection time | pending, saved or failed |
| published | trueor false |
|
| env | If the dataset is in preproduction envirenment or in production one | productionor preproduction |
| overwritted | If the data can be overwritten (only for being able to make dataset updates) | trueor false |
| verify | If this dataset contains data that is verified using blockchain | trueor false |
| protected | If it’s a protected layer | trueor false |
| geoInfo | If it contains intersectable geographical info | trueor false |
Filtering datasets
curl -X GET https://api.skydipper.com/v1/dataset?name=birds&provider=cartodb
For inclusive filtering with array props use ’@’
curl -X GET https://api.skydipper.com/v1/dataset?provider=cartodb@gee
Sorting
Basics of sorting
The API currently supports sorting by means of the sort parameter.
Sorting datasets
curl -X GET https://api.skydipper.com/v1/dataset?sort=name
Multiple sorting criteria can be used, separating them by commas.
Sorting datasets by multiple criteria
curl -X GET https://api.skydipper.com/v1/dataset?sort=name,description
You can specify the sorting order by prepending the criteria with either - or +. By default, asc order is assumed.
Explicit order of sorting
curl -X GET https://api.skydipper.com/v1/dataset?sort=-name,+description
Special sorting criteria
There are two special sorting criteria:
metadata: delegates sorting to the metadata component, sorting by the name field of the metadata.relevance: delegates sorting to the metadata component, sorting by the datasets which metadata better match the search criteria. Can only be used in conjunction with asearchparameter. Does not support ascending order.
Special search criteria must be used as sole sorting criteria, as it’s not possible to combine any of them with any other search criteria.
Sorting datasets with special criteria
curl -X GET https://api.skydipper.com/v1/dataset?sort=relevance&status=saved&search=agriculture
Relationships
Available relationships: Any dataset relationship [‘metadata’]
Including relationships
curl -X GET https://api.skydipper.com/v1/dataset?sort=slug,-provider,userId&status=saved&includes=metadata
Pagination
| Field | Description | Type |
|---|---|---|
| page[size] | The number elements per page | Number |
| page[number] | The page number | Number |
Paginating the output
curl -X GET https://api.skydipper.com/v1/dataset?sort=slug,-provider,userId&status=saved&includes=metadata&page[number]=1
curl -X GET https://api.skydipper.com/v1/dataset?sort=slug,-provider,userId&status=saved&includes=metadata&page[number]=2
How to get a specific dataset
To get a dataset:
curl -X GET https://api.skydipper.com/v1/dataset/51943691-eebc-4cb4-bdfb-057ad4fc2145
Response:
{
"data": {
"id": "098b33df-6871-4e53-a5ff-b56a7d989f9a",
"type": "dataset",
"attributes": {
"name": "Subnational Political Boundaries",
"slug": "Politcial-Boundaries-GADM-adminitrative-level-1-1490086842541",
"type": "tabular",
"subtitle": "GADM",
"application": ["skydipper"],
"dataPath": null,
"attributesPath": null,
"connectorType": "rest",
"provider": "cartodb",
"userId": "57a0aa1071e394dd32ffe137",
"connectorUrl": "https://wri-01.carto.com/tables/gadm28_adm1/public",
"tableName": "gadm28_adm1",
"status": "saved",
"published": true,
"overwrite": false,
"verified": false,
"blockchain": null,
"subscribable": null,
"mainDateField": null,
"env": "production",
"geoInfo": true,
"protected": true,
"legend": {
"date": [],
"region": [],
"country": [],
"nested": []
},
"clonedHost": null,
"errorMessage": null,
"taskId": null,
"updatedAt": "2018-11-21T13:54:56.285Z",
"dataLastUpdated": null
}
}
}
To get the dataset including its relationships:
curl -X GET https://api.skydipper.com/v1/dataset/06c44f9a-aae7-401e-874c-de13b7764959?includes=metadata
Creating a Dataset
To create a dataset, you will need an authorization token. Follow the steps of this guide to get yours.
To create a dataset, you need to define all of the required fields in the request body. The fields that compose a dataset are:
| Field | Description | Type | Values | Required |
|---|---|---|---|---|
| name | Dataset name | Text | Any Text | Yes |
| type | Dataset type | Text | Any Text | No |
| subtitle | Dataset subtitle | Text | Any Text | No |
| application | Applications the dataset belongs to | Array | Any valid application name(s) | Yes |
| connectorType | Connector type | Text | rest, document, wms | Yes |
| provider | The connectorType provider | Text | cartodb, feature service, gee | Yes |
| connectorUrl | Url of the data source | Url | Any url | Yes (except for gee) |
| tableName | Table name | Text | Any valid table name | No (just for GEE datasets) |
| data | JSON DATA only for json connector if connectorUrl not present | JSON | [{},{},{}] | No (just for json if connectorUrl is not present) |
| dataPath | Path to the data in a json dataset | Text | Any valid JSON key | No (just for json if connectorUrl is not present) |
| dataAttributes | Data fields - for json connector if data present | Object | {“key1”: {“type”: “string”},… } | No (just for json if connectorUrl is not present) |
| legend | Legend for dataset. Keys for special fields | Object | “legend”: {“long”: “123”, “lat”: “123”, “country”: [“pais”], “region”: [“barrio”], “date”: [“startDate”, “endDate”]}} | No |
| overwrite | It allows to overwrite dataset data | Boolean | true/false | No |
| published | To set a public or private dataset | Boolean | true/false | No |
| protected | If it’s a protected layer (not possible to delete if it’s true) | Boolean | true/false | No |
| verified | To generate a verified blockchain of the dataset | Boolean | true/false | No |
There are some differences between datasets types.
Rest-Carto datasets
curl -X POST https://api.skydipper.com/v1/dataset \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"connectorType":"rest",
"provider":"cartodb",
"connectorUrl":"<cartoUrl>",
"application":[
"your", "apps"
],
"name":"Example Carto Dataset"
}'
A real example:
curl -X POST https://api.skydipper.com/v1/dataset \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"connectorType":"rest",
"provider":"cartodb",
"connectorUrl":"https://wri-01.carto.com/tables/wdpa_protected_areas/table",
"application":[
"skydipper"
],
"name":"World Database on Protected Areas -- Global"
}'
Rest-ArcGIS feature Service
curl -X POST https://api.skydipper.com/v1/dataset \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"connectorType":"rest",
"provider":"featureservice",
"connectorUrl":"https://services.arcgis.com/uDTUpUPbk8X8mXwl/arcgis/rest/services/Public_Schools_in_Onondaga_County/FeatureServer/0?f=json",
"application":[
"skydipper"
],
"name":"Uncontrolled Public-Use Airports -- U.S."
}'
Rest-GEE
curl -X POST https://api.skydipper.com/v1/dataset \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"connectorType":"rest",
"provider":"gee",
"tableName": "JRC/GSW1_0/GlobalSurfaceWater"
"application":[
"skydipper"
],
"name":"Water occurrence"
}'
Updating a Dataset
In order to modify the dataset, you can PATCH a request. It accepts the same parameters as the create dataset endpoint, and you will need an authentication token.
An example update request:
curl -X PATCH https://api.skydipper.com/v1/dataset/<dataset-id> \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"name": "Another name for the dataset"
}'
Deleting a Dataset
When a dataset is deleted the user’s applications that were present on the dataset will be removed from it. If this results in a dataset without applications, the dataset itself will be then deleted.
Datasets can be deleted either by any user with role ADMIN or by the user with role MANAGER that created them. Note that the deletion process cascades; deleting a dataset will also remove all layer, vocabularies, and metadata entities associated with it.
curl -X DELETE https://api.skydipper.com/v1/dataset/<dataset-id> \
-H "Authorization: Bearer <your-token>"
-H "Content-Type: application/json"
Cloning a Dataset
curl -X POST https://api.skydipper.com/v1/dataset/5306fd54-df71-4e20-8b34-2ff464ab28be/clone \
-H "Authorization: Bearer <your-token>"
-H "Content-Type: application/json" -d \
'{
"dataset": {
"datasetUrl": "/query/5306fd54-df71-4e20-8b34-2ff464ab28be?sql=select%20%2A%20from%20data%20limit%2010",
"application": [
"your",
"apps"
]
}
}'
Layer
What is a Layer?
A layer is a geographical representation of a Dataset’s data.
Layer contains the following fields:
| Field | Description | Type |
|---|---|---|
| userId | Id of the owner | Text |
| application | Application to which the dataset belongs | Array |
| iso | The isos to which the dataset belongs | Array |
| slug | Unique identifier of the layer | Text |
| name | Name of the layer | Url |
| description | Description of the layer | Array |
| dataset | UuId of the dataset that the layer belongs | Text |
| layerConfig | Custom configuration | Object |
| legendConfig | Custom configuration | Object |
| applicationConfig | Custom configuration | Object |
| staticImageConfig | Custom configuration | Object |
| default | If it’s a default layer for the dataset that it belongs | Boolean |
| protected | If it’s a protected layer (not is possible to delete if it’s true) | Boolean |
| published | Is the layer published? | Boolean |
| env | environment in witch the layer was published, one of preproduction or production |
Text |
How obtain all layers
To obtain all layers:
curl -X GET https://api.skydipper.com/v1/layer
Example response:
{
"data":[
{
"id": "e5c3e7c5-19ae-4ca0-a461-71f1f67aa553",
"type": "layer",
"attributes": {
"slug": "total-co2-emissions-by-year",
"userId": "5858f37140621f11066fb2f7",
"application": [
"skydipper"
],
"name": "Total CO2 emissions by year",
"default": false,
"dataset": "11de2bc1-368b-42ed-a207-aaff8ece752b",
"provider": "cartodb",
"iso": [],
"description": null,
"layerConfig": {
"account": "skydipper",
"body": {
"maxzoom": 18,
"minzoom": 3,
"layers": [
{
"type": "mapnik",
"options": {
"sql": "SELECT * cait_2_0_country_ghg_emissions_filtered",
"cartocss": "",
"cartocss_version": "2.3.0"
}
}
]
}
},
"legendConfig": {
"marks": {
"type": "rect",
"from": {
"data": "table"
}
}
},
"applicationConfig": {},
"staticImageConfig": {}
}
}
],
"links":{
"first":"https://api.skydipper.com/v1/layer?page%5Bnumber%5D=1",
"prev":"https://api.skydipper.com/v1/layer?page%5Bnumber%5D=1",
"next":"https://api.skydipper.com/v1/layer?page%5Bnumber%5D=2&page%5Bsize%5D=10",
"last":"https://api.skydipper.com/v1/layer?page%5Bnumber%5D=64&page%5Bsize%5D=10",
"self":"https://api.skydipper.com/v1/layer?page%5Bnumber%5D=1&page%5Bsize%5D=10"
},
"meta": {
"total-pages": 63,
"total-items": 628,
"size": 10
}
}
Filter params
Available filters:
| Field | Description | Type |
|---|---|---|
| name | Filter the layers whose name contains the filter text | Text |
| dataset | Filter the layers by dataset uuid | Text |
| sort | Sort json response by specific attributes | Text |
| status | Filter layers on status (pending, saved, failed, all) | Text |
| published | Filter layers on published status (true, false) | Boolean |
| app | Filter layers on application (prep, gfw, etc..) | Text |
| env | Environment in witch the layer was published, one of preproduction or production |
Text |
Return the layers filtered by those whose name contains emissions
curl -X GET https://api.skydipper.com/v1/layer?name=emissions
Return the layers filtered by dataset
curl -X GET https://api.skydipper.com/v1/layer?dataset=11de2bc1-368b-42ed-a207-aaff8ece752b
curl -X GET https://api.skydipper.com/v1/dataset/11de2bc1-368b-42ed-a207-aaff8ece752b/layer
Sort by name
curl -X GET https://api.skydipper.com/v1/layer?sort=name
Filter layers by status
curl -X GET https://api.skydipper.com/v1/layer?status=failed
Filter layers by published status
curl -X GET https://api.skydipper.com/v1/layer?published=false
Return the layers filtered by those whose applications contain skydipper
curl -X GET https://api.skydipper.com/v1/layer?app=skydipper
Pagination params
| Field | Description | Type |
|---|---|---|
| page[size] | Number elements per page | Number |
| page[number] | Number of page | Number |
Return the layers of page 2 with 5 elements per page
curl -X GET https://api.skydipper.com/v1/layer?page[size]=5&page[number]=2
How obtain a layer for specific dataset
To obtain the layer:
curl -X GET https://api.skydipper.com/v1/dataset/11de2bc1-368b-42ed-a207-aaff8ece752b/layer/e5c3e7c5-19ae-4ca0-a461-71f1f67aa553
curl -X GET https://api.skydipper.com/v1/layer/e5c3e7c5-19ae-4ca0-a461-71f1f67aa553
Example response:
{
"data": {
"id": "e5c3e7c5-19ae-4ca0-a461-71f1f67aa553",
"type": "layer",
"attributes": {
"slug": "total-co2-emissions-by-year",
"userId": "5858f37140621f11066fb2f7",
"application": [
"skydipper"
],
"name": "Total CO2 emissions by year",
"default": false,
"dataset": "11de2bc1-368b-42ed-a207-aaff8ece752b",
"provider": "cartodb",
"iso": [],
"description": null,
"layerConfig": {
"account": "skydipper",
"body": {
"maxzoom": 18,
"minzoom": 3,
"layers": [
{
"type": "mapnik",
"options": {
"sql": "SELECT * cait_2_0_country_ghg_emissions_filtered",
"cartocss": "",
"cartocss_version": "2.3.0"
}
}
]
}
},
"legendConfig": {
"marks": {
"type": "rect",
"from": {
"data": "table"
}
}
},
"applicationConfig": {},
"staticImageConfig": {}
}
},
"meta": {
"status": "saved",
"published": true,
"updatedAt": "2017-01-23T16:51:42.571Z",
"createdAt": "2017-01-23T16:51:42.571Z"
}
}
Create a Layer
To create a layer, you need to define all of the required fields in the request body. The fields that compose a layer are:
| Field | Description | Type | Values | Required |
|---|---|---|---|---|
| name | Name of the layer | Text | Any Text | Yes |
| description | Description of the dataset | Text | Any text | No |
| application | Application to which the layer belongs | Array | gfw, forest-atlas, skydipper, prep, aqueduct, data4sdg | Yes |
| layerConfig | Custom configuration | Object | Valid object | No |
| legendConfig | Custom configuration | Object | Valid object | No |
| applicationConfig | Custom configuration | Object | Valid object | No |
| staticImageConfig | Custom configuration | Object | Valid object | No |
| iso | Isos to which the layer belongs | Array | BRA, ES | No |
| dataset | UuId of the dataset | Text | Uuid of Dataset | No |
| protected | If it’s a protected layer (not is possible to delete if it’s true) | Boolean | true-false | No |
To create a layer, you have to do a POST request with the following body:
curl -X POST https://api.skydipper.com/v1/dataset/<dataset_id>/layer \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"application":[
"your", "apps"
],
"name":"Example layer",
"status": 1
}'
The following structure was previously supported but should now be considered deprecated:
curl -X POST https://api.skydipper.com/v1/dataset/<dataset_id>/layer \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"layer": {
"application":[
"your", "apps"
],
"name":"Example layer",
"status": 1
}
}'
Update a Layer
To update a layer, you need to define all of the required fields in the request body. The fields that compose a layer are:
| Field | Description | Type | Values | Required |
|---|---|---|---|---|
| name | Name of the layer | Text | Any Text | Yes |
| description | Description of the dataset | Text | Any text | No |
| application | Application to which the layer belongs | Array | gfw, forest-atlas, skydipper, prep, aqueduct, data4sdg | Yes |
| layerConfig | Custom configuration | Object | Valid object | No |
| legendConfig | Custom configuration | Object | Valid object | No |
| applicationConfig | Custom configuration | Object | Valid object | No |
| staticImageConfig | Custom configuration | Object | Valid object | No |
| iso | The isos to which the layer belongs | Array | BRA, ES | No |
| dataset | UuId of the dataset | Text | Uuid of Dataset | No |
To create a layer, you have to do a POST requestwith the following body:
curl -X PATCH https://api.skydipper.com/v1/dataset/<dataset_id>/layer/<layer_id> \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" -d \
'{
"layer": {
"application":[
"your", "apps"
],
"name":"New Example layer Name",
"layerConfig": {}
}
}'
Delete a Layer
curl -X DELETE https://api.skydipper.com/v1/dataset/<dataset_id>/layer/<layer_id> \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json"
Metadata
Metadata definition
Metadata can be any kind of data associated to an existing resource (i.e. a dataset).
Some fields are important to identify the entity properly; others are just optional and give extra information about it.
| Field | Description | Type |
|---|---|---|
| application | The metadata application | String |
| language | The metadata language | String |
| dataset | The associated dataset id to the metadata | String |
| resource | The resource associated to the metadata | Object |
| – id | Resource id | String |
| – type | Resource type | String |
| name | The metadata name | String |
| description | The metadata description | String |
| source | The metadata source | String |
| citation | The metadata citation | String |
| license | The metadata license type | String |
| info | Some info about the metadata | Object |
| units | Measurement units | Object |
Creating a metadata object
| Field | Required/Optional |
|---|---|
| application | required |
| language | required |
| dataset | required |
| name | optional |
| description | optional |
| source | optional |
| citation | optional |
| license | optional |
| info | optional |
| units | optional |
The “application” and “language” attributes are required and it is mandatory to include them in the payload.
curl -X POST https://api.skydipper.com/v1/dataset/<dataset-id>/metadata \
-H "Content-Type: application/json" -d \
'{
"application": <app>,
"language": <language>
}'
Real example
curl -X POST https://api.skydipper.com/v1/dataset/942b3f38-9504-4273-af51-0440170ffc86/metadata \
-H "Content-Type: application/json" -d \
'{
"application": "skydipper",
"language": "en"
}'
Response: 200 OK HTTP RESPONSE + JSON-API-LIKE BODY
{
"data": [
{
"id": "942b3f38-9504-4273-af51-0440170ffc86-dataset-942b3f38-9504-4273-af51-0440170ffc86-rw-en",
"type": "metadata",
"attributes": {
"dataset": "942b3f38-9504-4273-af51-0440170ffc86",
"application": "skydipper",
"resource": {
"type": "dataset",
"id": "942b3f38-9504-4273-af51-0440170ffc86"
},
"language": "en",
"createdAt": "2017-01-20T08:07:53.272Z",
"updatedAt": "2017-01-20T08:07:53.272Z",
"status": "published"
}
}
]
}
It could respond with a 401 status code if the request is not authenticated, 403 if the request is not allowed to do that operation, 400 if the request is not well formatted, or 5XX HTTP codes in other cases.
Getting metadata
application filter:
application: skydipper
language filter:
language: select between available languages (select one or some of them)
limit filter:
limit: the desired number
Custom param for /metadata endpoint:
type: [dataset]
curl -X GET https://api.skydipper.com/v1/dataset/<dataset-id>/metadata
Real example
curl -X GET https://api.skydipper.com/v1/dataset/942b3f38-9504-4273-af51-0440170ffc86/metadata
Updating a metadata
Partial update:
The “application” and “language” attributes are required and it is mandatory to include them in the payload.
curl -X PATCH https://api.skydipper.com/v1/dataset/<dataset-id>/metadata \
-H "Content-Type: application/json" -d \
'{
"application": <app>,
"language": <language>
}'
Real example
curl -X PATCH https://api.skydipper.com/v1/dataset/942b3f38-9504-4273-af51-0440170ffc86/metadata \
-H "Content-Type: application/json" -d \
'{
"application": "skydipper",
"language": "en",
"name": "Cloud Computing Market - USA - 2016",
"source": "http://www.forbes.com/",
"info": {
"summary": "These and many other insights are from the latest series of cloud computing forecasts and market estimates produced by IDC, Gartner, Microsoft and other research consultancies. Amazon’s decision to break out AWS revenues and report them starting in Q1 FY2015 is proving to be a useful benchmark for tracking global cloud growth. In their latest quarterly results released on January 28, Amazon reported that AWS generated $7.88B in revenues and attained a segment operating income of $1.863B. Please see page 8 of the announcement for AWS financials. For Q4, AWS achieved a 28.5% operating margin (% of AWS net sales).",
"author": "Louis Columbus",
"date": "MAR 13, 2016 @ 10:42 PM",
"link": "http://www.forbes.com/sites/louiscolumbus/2016/03/13/roundup-of-cloud-computing-forecasts-and-market-estimates-2016/#5875cf0074b0"
}
}'
Response
{
"data": [
{
"id": "942b3f38-9504-4273-af51-0440170ffc86-dataset-942b3f38-9504-4273-af51-0440170ffc86-skydipper-en",
"type": "metadata",
"attributes": {
"dataset": "942b3f38-9504-4273-af51-0440170ffc86",
"application": "skydipper",
"resource": {
"type": "dataset",
"id": "942b3f38-9504-4273-af51-0440170ffc86"
},
"language": "en",
"name": "Cloud Computing Market - USA - 2016",
"source": "http://www.forbes.com/",
"info": {
"summary": "These and many other insights are from the latest series of cloud computing forecasts and market estimates produced by IDC, Gartner, Microsoft and other research consultancies. Amazon’s decision to break out AWS revenues and report them starting in Q1 FY2015 is proving to be a useful benchmark for tracking global cloud growth. In their latest quarterly results released on January 28, Amazon reported that AWS generated $7.88B in revenues and attained a segment operating income of $1.863B. Please see page 8 of the announcement for AWS financials. For Q4, AWS achieved a 28.5% operating margin (% of AWS net sales).",
"author": "Louis Columbus",
"date": "MAR 13, 2016 @ 10:42 PM",
"link": "http://www.forbes.com/sites/louiscolumbus/2016/03/13/roundup-of-cloud-computing-forecasts-and-market-estimates-2016/#5875cf0074b0"
},
"createdAt": "2017-01-20T08:07:53.272Z",
"updatedAt": "2017-01-20T08:40:30.190Z",
"status": "published"
}
}
]
}
Deleting a metadata
The “application” and “language” attributes are required and it is mandatory to include them in the query params.
curl -X DELETE https://api.skydipper.com/v1/dataset/<dataset-id>/metadata?application=<app-id>&language=<language>
Real example
curl -X DELETE https://api.skydipper.com/v1/dataset/942b3f38-9504-4273-af51-0440170ffc86/metadata?application=skydipper&language=en \
Getting all
curl -X GET https://api.skydipper.com/v1/metadata
Real examples
curl -X GET https://api.skydipper.com/v1/metadata
curl -X GET https://api.skydipper.com/v1/metadata?type=dataset
curl -X GET https://api.skydipper.com/v1/metadata?application=skydipper&language=es,en&limit=20
curl -X GET https://api.skydipper.com/v1/metadata?application=skydipper,gfw&language=en&type=dataset
curl -X GET https://api.skydipper.com/v1/metadata?language=en
Finding (getting) by ids
The “ids” property is required in the payload, and in other case the endpoint responds with a 400 HTTP ERROR (Bad Request) This property can be an Array or a String (comma-separated) payload -> {“ids”: [“112313”, “111123”]} payload -> {“ids”: “112313, 111123”}
application filter:
application: skydipper (select one or some of them)
language filter:
language: select between available languages (select one or some of them)
limit filter:
limit: the desired number
Custom param for the metadata endpoint:
type: [dataset]
curl -X POST https://api.skydipper.com/v1/dataset/metadata/find-by-ids \
-H "Content-Type: application/json" -d \
'{
"ids": [<ids>]
}'
Real example
curl -X POST https://api.skydipper.com/v1/dataset/metadata/find-by-ids \
-H "Content-Type: application/json" -d \
'{
"ids": "b000288d-7037-43ba-aa34-165eab549613, 942b3f38-9504-4273-af51-0440170ffc86"
}'
Response
{
"data": [
{
"id": "b000288d-7037-43ba-aa34-165eab549613-dataset-b000288d-7037-43ba-aa34-165eab549613-prep-en",
"type": "metadata",
"attributes": {
"dataset": "b000288d-7037-43ba-aa34-165eab549613",
"application": "prep",
"resource": {
"type": "dataset",
"id": "b000288d-7037-43ba-aa34-165eab549613"
},
"language": "en",
"name": "Projected temperature change",
"description": "The Puget Sound region is projected to warm rapidly during the 21st century. Prior to mid-century, the projected increase in air temperatures is about the same for all greenhouse gas scenarios, a result of the fact that a certain amount of warming is already “locked in” due to past emissions. After about 2050, projected warming depends on the amount of greenhouse gases emitted globally in the coming decades. For the 2050s (2040-2069, relative to 1970-1999), annual average air temperature is projected to rise +4.2°F to +5.9°F, on average, for a low (RCP 4.5) and a high (RCP 8.5) greenhouse gas scenario. These indicators are derived from the Multivariate Adaptive Constructed Analogs (MACA) CMIP5 Future Climate Dataset from the University of Idaho. For more information about this analysis, please see http://cses.washington.edu/picea/mauger/ps-sok/ps-sok_sec12_builtenvironment_2015.pdf. For more information about the MACA CMIP5 Future Climate Dataset please see http://maca.northwestknowledge.net/index.php",
"source": "http://maca.northwestknowledge.net",
"citation": "Abatzoglou, J. T., Brown, T. J. 2012. A comparison of statistical downscaling methods suited for wildfire applications. International Journal of Climatology, 32(5), 772-780. doi: http://dx.doi.org/10.1002/joc.2312 ",
"license": "Public domain",
"info": {
"organization": "Joe Casola, University of Washington",
"license": "Public domain",
"source": "http://maca.northwestknowledge.net",
"citation": "Abatzoglou, J. T., Brown, T. J. 2012. A comparison of statistical downscaling methods suited for wildfire applications. International Journal of Climatology, 32(5), 772-780. doi: http://dx.doi.org/10.1002/joc.2312 ",
"description": "The Puget Sound region is projected to warm rapidly during the 21st century. Prior to mid-century, the projected increase in air temperatures is about the same for all greenhouse gas scenarios, a result of the fact that a certain amount of warming is already “locked in” due to past emissions. After about 2050, projected warming depends on the amount of greenhouse gases emitted globally in the coming decades. For the 2050s (2040-2069, relative to 1970-1999), annual average air temperature is projected to rise +4.2°F to +5.9°F, on average, for a low (RCP 4.5) and a high (RCP 8.5) greenhouse gas scenario. These indicators are derived from the Multivariate Adaptive Constructed Analogs (MACA) CMIP5 Future Climate Dataset from the University of Idaho. For more information about this analysis, please see http://cses.washington.edu/picea/mauger/ps-sok/ps-sok_sec12_builtenvironment_2015.pdf. For more information about the MACA CMIP5 Future Climate Dataset please see http://maca.northwestknowledge.net/index.php",
"short-description": "Projected temperature change in the Puget Sound Lowlands relative to average temperature between 1950-2005. Light colored lines in the background show the range of projections. All climate scenarios project warming for the Puget Sound region during the 21st century.",
"subtitle": "",
"title": "Projected temperature change"
},
"createdAt": "2016-12-13T10:02:28.337Z",
"updatedAt": "2016-12-13T10:03:02.445Z",
"status": "published"
}
},
{
"id": "942b3f38-9504-4273-af51-0440170ffc86-dataset-942b3f38-9504-4273-af51-0440170ffc86-skydipper-en",
"type": "metadata",
"attributes": {
"dataset": "942b3f38-9504-4273-af51-0440170ffc86",
"application": "skydipper",
"resource": {
"type": "dataset",
"id": "942b3f38-9504-4273-af51-0440170ffc86"
},
"language": "en",
"name": "Cloud Computing Market - USA - 2016",
"source": "http://www.forbes.com/",
"info": {
"link": "http://www.forbes.com/sites/louiscolumbus/2016/03/13/roundup-of-cloud-computing-forecasts-and-market-estimates-2016/#5875cf0074b0",
"date": "MAR 13, 2016 @ 10:42 PM",
"author": "Louis Columbus",
"summary": "These and many other insights are from the latest series of cloud computing forecasts and market estimates produced by IDC, Gartner, Microsoft and other research consultancies. Amazon’s decision to break out AWS revenues and report them starting in Q1 FY2015 is proving to be a useful benchmark for tracking global cloud growth. In their latest quarterly results released on January 28, Amazon reported that AWS generated $7.88B in revenues and attained a segment operating income of $1.863B. Please see page 8 of the announcement for AWS financials. For Q4, AWS achieved a 28.5% operating margin (% of AWS net sales)."
},
"createdAt": "2017-01-20T08:07:53.272Z",
"updatedAt": "2017-01-20T08:40:30.190Z",
"status": "published"
}
}
]
}
Microservices
A list of information related to the microservices
List all registered microservices
To obtain a list of all the registered microservices:
curl -X GET https://api.skydipper.com/api/v1/microservice \
-H "Authorization: Bearer <your-token>"
Example response:
[
{
"infoStatus": {
"numRetries": 0,
"error": null,
"lastCheck": "2019-02-04T14:05:30.748Z"
},
"pathInfo": "/info",
"pathLive": "/ping",
"status": "active",
"cache": [],
"uncache": ["dataset"],
"tags": [
"dataset"
],
"_id": "id",
"name": "Dataset",
"url": "http://dataset.default.svc.cluster.local:3000",
"version": 1,
"endpoints": [
{
"redirect": {
"method": "GET",
"path": "/api/v1/dataset"
},
"path": "/v1/dataset",
"method": "GET"
},
{
"redirect": {
"method": "POST",
"path": "/api/v1/dataset/find-by-ids"
},
"path": "/v1/dataset/find-by-ids",
"method": "POST"
},
...
],
"updatedAt": "2019-01-24T13:04:46.728Z",
"swagger": "{}"
},
...
}
}
Delete microservice
To remove a microservice:
curl -X DELETE https://api.skydipper.com/api/v1/microservice/:id \
-H "Authorization: Bearer <your-token>"
Notes
Keep in mind that this does not actually delete the microservice, instead it schedules it for being removed. There’s a cron task that does the actual deleting, so the process is async.
GeoAI
Service for statistical analysis tools.
Trends
Examine long-term changes in a 1-D dataset, using moving average (box-car) de-treding (i.e. low-pass filter) and a Monte Carlo resampling to calculate the significance of the low-frequency variance.
url = "https://api.skydipper.com/v1/geoai/trends"
querystring = {"mc_number":"10000",
"bin_number":"100",
"window":"5"}
payload = "{\"timeseries\": {\"2001\": 8523609.893269539, \"2002\": 9219075.336818695, \"2003\": 5745394.048210621, \"2004\": 16352804.901271343, \"2005\": 11950375.210030556, \"2006\": 18535092.244664192, \"2007\": 15964553.06836462, \"2008\": 12015146.018202782, \"2009\": 17515508.700252533, \"2010\": 14973976.22736454, \"2011\": 10555302.132576942, \"2012\": 19785808.554305553, \"2013\": 15784503.92861414, \"2014\": 18598649.662708282, \"2015\": 16366608.645088673, \"2016\": 26919829.052940845, \"2017\": 24389565.014420033, \"2018\": 31650039.900456905}}"
headers = {
'Content-Type': "application/json",
'cache-control': "no-cache"
}
response = requests.post(url, data=payload, headers=headers, params=querystring)
print(response.text)
Example response:
{
"data": {
"attributes": {
"anomaly": 13226686.577202797,
"anomaly_uncertainty": 6605963.307585477,
"bin_number": 100,
"description": "Increase of 1.3e+07 over observation period has an associated p-value of 0.001\u00b1 1.000 0.948.",
"lower_p": 0.9480426688037374,
"mc_number": 10000,
"p": 0.9994235963381208,
"upper_p": 0.9999994544351509,
"window": 5
},
"id": null,
"type": "mc_timeseries_analysis"
}
}
Geostore
What is Geostore?
Geostore is a geojson database. You can save your geojson or obtain geojson by country, region, Protected areas, etc.
Geostore object contains the following fields:
| Field | Description | Type |
|---|---|---|
| id | Id of the geostore | Text |
| geojson | Geojson with the geometry | Object |
| hash | MD5 hash generated from geojson. Is the same that the id | Object |
| provider | This field should be completed if the geostore was created from a provider | Object |
| – type | Provider type | Text |
| – table | Table name | Text |
| – user | User of the account | Text |
| – filter | Conditions to obtain the geojson. It is possible use AND & OR conditions. This conditions must only return one row. | Text |
| areaHa | Area in Hectares of the geojson | Number |
| bbox | Bounding box of the geojson | Array |
Create Geostore
You can create a geostore in 4 different ways:
With a Geojson
If you have your own geojson, you can save it in geostore. To create the geostore, you need to define all the required fields in the request body. The fields that compose a geostore are:
| Field | Description | Type | Values | Required |
|---|---|---|---|---|
| geojson | Geojson with your geometry | Object | Yes |
To create a Geostore, you have to do a POST query with the following body:
curl -X POST https://api.skydipper.com/v1/geostore \
-H "Content-Type: application/json" -d \
'{
"geojson": <yourGeoJSONObject>
}'
Real example
curl -X POST https://api.skydipper.com/v1/geostore \
-H "Content-Type: application/json" -d \
'{
"geojson":{
"type":"FeatureCollection",
"features":[
{
"type":"Feature",
"properties":{
},
"geometry":{
"type":"LineString",
"coordinates":[
[
-3.9942169189453125,
41.044922165782175
],
[
-3.995418548583985,
41.03767166215326
],
[
-3.9842605590820312,
41.03844854003296
],
[
-3.9844322204589844,
41.04589315472392
],
[
-3.9942169189453125,
41.044922165782175
]
]
}
},
{
"type":"Feature",
"properties":{
},
"geometry":{
"type":"Polygon",
"coordinates":[
[
[
-4.4549560546875,
40.84706035607122
],
[
-4.4549560546875,
41.30257109430557
],
[
-3.5211181640624996,
41.30257109430557
],
[
-3.5211181640624996,
40.84706035607122
],
[
-4.4549560546875,
40.84706035607122
]
]
]
}
}
]
}
}'
The response will be 200 if the geostore saves correctly and returns the geostore object with all information:
Example response
{
"data":{
"type":"geoStore",
"id":"c9bacccfb9c3fe225dc67545bb93a5cb",
"attributes":{
"geojson":{
"features":[
{
"type":"Feature",
"geometry":{
"type":"Polygon",
"coordinates":[
[
[
-4.4549560546875,
40.84706035607122
],
[
-4.4549560546875,
41.30257109430557
],
[
-3.5211181640624996,
41.30257109430557
],
[
-3.5211181640624996,
40.84706035607122
],
[
-4.4549560546875,
40.84706035607122
]
]
]
}
}
],
"crs":{
},
"type":"FeatureCollection"
},
"hash":"c9bacccfb9c3fe225dc67545bb93a5cb",
"provider":{
},
"areaHa":397372.34122605197,
"bbox":[
-4.4549560546875,
40.84706035607122,
-3.5211181640624996,
41.30257109430557
]
}
}
}
From country
If you need obtain the geostore of a country, you can obtain it with the ISO3 code in the Geostore API.
GET https://api.skydipper.com/v1/geostore/admin/<ISO3>
curl -X GET https://api.skydipper.com/v1/geostore/admin/<ISO3>
Real example obtaining the geostore of Spain
shell curl -X GET https://api.skydipper.com/v1/geostore/admin/ESP
Country list
A list of countries can be obtained from this endpoint.
curl -X GET https://api.skydipper.com/v1/geostore/admin/list
Example response
{
"data": [{
"geostoreId": "35a6d982388ee5c4e141c2bceac3fb72",
"iso": "ESP",
"name": "Spain"
}, {
"geostoreId": "8f77fe62cf15d5098ba0ee11c5126aa6",
"iso": "FRA",
"name": "France"
}, {
"geostoreId": "1d568c183033da6c17cc28c4aecf1bcf",
"iso": "cod",
"name": "Democratic Republic of the Congo"
}]
}
From country and region
If you need obtain the geostore of a region in a country, you can obtain it with the ISO3 and region code:
GET https://api.skydipper.com/v1/geostore/admin/<ISO3>/<regionCode>
curl -X GET https://api.skydipper.com/v1/geostore/admin/<ISO3>/<regionCode>
Real example obtaining the geostore of Madrid’s Comunity in Spain
curl -X GET https://api.skydipper.com/v1/geostore/admin/ESP/8
From World Database on Protected Areas (wdpa)
Is possible obtain the geostore of a World Database on Protected Areas of the world. You only need the id of the protected area (WDPA). World Database on Protected Areas web
GET https://api.skydipper.com/v1/geostore/wdpa/<wdpaId>
curl -X GET https://api.skydipper.com/v1/geostore/wdpa/<wdpaId>
Real example obtaining the geostore of ‘Sierra de Guadarrama’ protected area
curl -X GET https://api.skydipper.com/v1/geostore/wdpa/555538160
From Carto
If your geojson is in carto table, is possible import this geojson in geostore. To import the geojson in geostore, you need to define all of the required fields in the request body. The fields that compose a import are:
| Field | Description | Type | Values | Required |
|---|---|---|---|---|
| provider | Provider of data | Object | Yes | |
| – type | Provider type | Text | carto | Yes |
| – table | Table name | Text | Yes | |
| – user | User of the account | Text | Yes | |
| – filter | Conditions to obtain the geojson. Is possible put and and or conditions. This conditions must only return one row. | Text | Yes |
To import a Geostore, you have to do a POST with the following body:
curl -X POST https://api.skydipper.com/v1/geostore \
-H "Content-Type: application/json" -d \
'{
"provider":{
"type": "carto",
"table": <tableName>,
"user": <userName>,
"filter": <conditions>
}
}'
Real example
curl -X POST https://api.skydipper.com/v1/geostore \
-H "Content-Type: application/json" -d \
'{
"provider":{
"type": "carto",
"table": "gfw_mining",
"user": "wri-01",
"filter": "cartodb_id=573"
}
}'
Example response
{
"data": {
"type": "geoStore",
"id": "26f8975c4c647c19a2edaa11f23880a2",
"attributes": {
"geojson": {
"features": [
{
"type": "Feature",
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-74.0957370284411,
10.6814701233475
],
[
-74.0957357154309,
10.654348341203
],
[
-74.1100850695703,
10.6543473339623
],
[
-74.1100876551212,
10.6814691125096
],
[
-74.0957370284411,
10.6814701233475
]
]
]
]
}
}
],
"crs": {},
"type": "FeatureCollection"
},
"hash": "26f8975c4c647c19a2edaa11f23880a2",
"provider": {
"filter": "cartodb_id=573",
"user": "wri-01",
"table": "gfw_mining",
"type": "carto"
},
"areaHa": 471.001953054716,
"bbox": [
-74.1100876551212,
10.6543473339623,
-74.0957357154309,
10.6814701233475
]
}
}
}
Obtain a Geostore
To obtain a geostore, you only need the id of the Geostore. You can perform a GET request for the geostore with its id.
curl -X GET https://api.skydipper.com/v1/geostore/<geostoreId>
Real example obtaining one geostore
curl -X GET https://api.skydipper.com/v1/geostore/use/logging/26f8975c4c647c19a2edaa11f23880a2
Example response
{
"data": {
"type": "geoStore",
"id": "26f8975c4c647c19a2edaa11f23880a2",
"attributes": {
"geojson": {
"features": [
{
"type": "Feature",
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-74.0957370284411,
10.6814701233475
],
[
-74.0957357154309,
10.654348341203
],
[
-74.1100850695703,
10.6543473339623
],
[
-74.1100876551212,
10.6814691125096
],
[
-74.0957370284411,
10.6814701233475
]
]
]
]
}
}
],
"crs": {},
"type": "FeatureCollection"
},
"hash": "26f8975c4c647c19a2edaa11f23880a2",
"provider": {
"filter": "cartodb_id=573",
"user": "wri-01",
"table": "gfw_mining",
"type": "carto"
},
"areaHa": 471.001953054716,
"bbox": [
-74.1100876551212,
10.6543473339623,
-74.0957357154309,
10.6814701233475
]
}
}
}
Geodescriber
Geodescriber returns a text description of any Geostore or valid geojson area, in any langunage, dynamically.
Responses from Geodescriber have been tailored to different purposes. The (optional) argument app controls which flavour
description you will return.
The code for Geodescriber is hosted on Github.
Call Geodescriber with a Geostore ID
You can return a response from the Geodescriber by providing a geostore paramter in your GET request.
You can change the language of the response via the lang flag, using the ISO-2 codes.
curl --location --request GET 'https://api.skydipper.com/api/v1/geodescriber?geostore=<ID_HASH>&template=False&app=skydipper&lang=en'
Example Response
{
"data":{
"description":"The region's habitat is comprised of Cantabrian mixed forests. This region has no Intact Forest. The area has a predominantly warm and temperate climate with dry summers. It is part of the Temperate Broadleaf and Mixed Forests biome. The location is mostly land area with a large proportion of marine area. Area of 12,387km² located in a predominanty lowland area.",
"description_params":{},
"lang":"en",
"stats":{
"biome":{"4":1082227.4941176388},
"ecoregion":{"648":1082227.4941176388},
"intact2016":{"0":1666560.2431372453},
"isMountain":{"0":1603363.7882352876,
"1":63196.454901960824},
"koppen":{"32":222131.647058824,
"35":1222652.1764705782},
"seaLandFreshwater":{"0":1094287.9294117563,
"1":572272.3137254902}
},
"title":"Area in Galicia, Spain",
"title_params":{}
}
}
Geodescriber from valid GeoJSON
If the geometry does not correspond to a Geostore object, and you do not wish to create one, you can post a valid geojson directly to the Geodescriber service and return a response.
curl --location --request POST 'https://api.skydipper.com/v1/geodescriber/geom?lang=en&app=skydipper' \
--header 'Content-Type: application/json' \
--data-raw '{"geojson":{"type":"FeatureCollection","features":[{"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[-8.749999866114031,43.86562279054269],[-8.500000104532665,43.86562279054269],[-8.2500003429513,43.86562279054269],[-8.000000581369934,43.86562279054269],[-8.000000581369934,42.49423975448128],[-8.2500003429513,42.49423975448128],[-8.500000104532665,42.49423975448128],[-8.749999866114031,42.49423975448128],[-8.999999627695365,42.49423975448128],[-8.999999627695365,43.86562279054269],[-8.749999866114031,43.86562279054269]]]}}]}}'
Example Response
{
"data":{
"description":"The region's habitat is comprised of Cantabrian mixed forests. This region has no Intact Forest. The area has a predominantly warm and temperate climate with dry summers. It is part of the Temperate Broadleaf and Mixed Forests biome. The location is mostly land area with a large proportion of marine area. Area of 12,387km² located in a predominanty lowland area.",
"description_params":{},
"lang":"en",
"stats":{
"biome":{"4":1082227.4941176388},
"ecoregion":{"648":1082227.4941176388},
"intact2016":{"0":1666560.2431372453},
"isMountain":{"0":1603363.7882352876,
"1":63196.454901960824},
"koppen":{"32":222131.647058824,
"35":1222652.1764705782},
"seaLandFreshwater":{"0":1094287.9294117563,
"1":572272.3137254902}
},
"title":"Area in Galicia, Spain",
"title_params":{}
}
}
GeoDoctor
What is the GeoDoctor service?
GeoDoctor is a service to receive geospatial datafiles of various kinds, extract shapes, repair and simplify those shapes. The service responds with a valid geojson object that can be consumed by other Skydipper services such as Geostore.
File conversion is done with GDAL OGR2OGR), and optional cleaning and simplification is done using the visvalingam method, preserving features with Mapshaper.
An example with GEOSJON
Given an input file which contains:
{'type': 'FeatureCollection',
'features': [{'type': 'Feature',
'properties': {},
'geometry': {'type': 'Polygon',
'coordinates': [[[-8.690185546875, 32.8334428466495],
[-9.140625, 32.648625783736726],
[-9.052734375, 32.44488496716713],
[-8.865966796875, 32.27784451498272],
[-8.8330078125, 32.16631295696736],
[-8.865966796875, 32.008075959291055],
[-8.98681640625, 31.970803930433096],
[-9.33837890625, 31.93351676190369],
[-9.64599609375, 31.672083485607402],
[-9.755859375, 31.23159167205059],
[-9.481201171875, 31.005862904624205],
[-9.041748046875, 30.552800413453546],
[-9.0966796875, 30.173624550358536],
[-9.239501953125, 30.002516938570686],
[-8.3056640625, 29.707139348134145],
[-7.965087890625, 29.964452850852005],
[-7.921142578125, 30.259067203213018],
[-8.052978515625, 30.4297295750316],
[-8.3056640625, 30.524413269923986],
[-8.4375, 30.609549797190844],
[-8.3056640625, 30.798474179567823],
[-8.140869140625, 30.713503990354965],
[-8.074951171875, 30.675715404167743],
[-7.987060546875, 30.62845887475364],
[-7.91015625, 30.5717205651999],
[-7.822265625000001, 30.543338954230222],
[-7.701416015625001, 30.543338954230222],
[-7.679443359375, 30.6662659463233],
[-7.811279296874999, 30.80791068136646],
[-7.965087890625, 30.883369321692268],
[-8.052978515625, 30.92107637538488],
[-8.19580078125, 30.95876857077987],
[-8.28369140625, 30.987027960280326],
[-8.382568359375, 31.071755902820133],
[-8.349609375, 31.22219703210317],
[-8.06396484375, 31.287939892641734],
[-7.833251953125, 31.297327991404266],
[-6.723632812499999, 32.26855544621476],
[-7.822265625000001, 32.537551746769],
[-8.10791015625, 31.970803930433096],
[-8.646240234375, 31.96148355726853],
[-8.37158203125, 32.194208672875384],
[-8.118896484375, 32.676372772089834],
[-8.690185546875, 32.8334428466495]]]}}]}
From this file you can call the GeoDoctor service like this:
import requests
url = "http://api.skydipper.com/v1/geodoctor/convert"
querystring = {"simplify":"10", "clean":"true"}
files = {'file': open('<path_to_your_file>/<your_file.geosjon>', 'rb'), 'Accept': "application/json, text/pain, */*"}
r = requests.post(url, files=files, params=querystring)
print(r.json())
Which will result in a response like:
{'data': {'type': 'geoJSON',
'id': 'undefined',
'attributes': {'type': 'FeatureCollection',
'features': [{'type': 'Feature',
'properties': {'__id': 0},
'geometry': {'type': 'Polygon',
'coordinates': [[[-8.690185546875, 32.8334428466495],
[-6.723632812499999, 32.26855544621476],
[-7.833251953125, 31.297327991404266],
[-8.3056640625, 29.707139348134145],
[-9.755859375, 31.23159167205059],
[-8.690185546875, 32.8334428466495]]]}}]}}}
Note the simplification of simplify: 10 means that the shape has been simplified by 90%.
Example with Well-Known-text
You can upload Well-Known-Text format also, e.g. given a sample file with the contents:
index, geom,
1,"POLYGON ((-3.6694335937500004 40.896905775860006, -3.14208984375 40.58058466412761, -2.8125 40.81380923056958, -2.96630859375 41.16211393939692, -3.6035156249999996 41.44272637767212, -4.306640625 41.52502957323801, -5.053710937499999 41.47566020027821, -5.47119140625 41.32732632036622, -5.80078125 41.0130657870063, -5.91064453125 40.54720023441049, -5.888671875 40.06125658140474, -5.64697265625 39.690280594818034, -5.185546875 39.41922073655956, -4.32861328125 39.30029918615029, -3.427734375 39.30029918615029, -3.01025390625 39.554883059924016, -3.01025390625 39.87601941962116, -2.548828125 39.90973623453719, -2.57080078125 40.195659093364654, -3.97705078125 40.212440718286466, -3.97705078125 39.9434364619742, -3.5595703125 39.926588421909436, -3.5815429687499996 39.757879992021756, -4.50439453125 39.690280594818034, -5.053710937499999 39.8928799002948, -5.20751953125 40.07807142745009, -5.295410156249999 40.39676430557203, -5.3173828125 40.84706035607122, -4.89990234375 41.02964338716638, -4.4384765625 41.062786068733026, -3.80126953125 41.062786068733026, -3.6694335937500004 40.896905775860006))"
You can use that file as an input to the service like so:
import requests
url = "http://api.skydipper.com/v1/geodoctor/convert"
querystring = {"simplify":"90", "clean":"true"}
files = {'file': open('<path_to_your_file>/<your_file.csv>', 'rb'), 'Accept': "application/json, text/pain, */*"}
r = requests.post(url, files=files, params=querystring)
Gives a response of:
{'geojson': {'type': 'FeatureCollection',
'features': [{'type': 'Feature',
'properties': {'index': '1', 'field_3': None, '__id': 0},
'geometry': {'type': 'Polygon',
'coordinates': [[[-3.66943359375, 40.896905775860006],
[-3.80126953125, 41.062786068733026],
[-4.89990234375, 41.02964338716638],
[-5.3173828125, 40.84706035607122],
[-5.20751953125, 40.07807142745009],
[-5.053710937499999, 39.8928799002948],
[-4.50439453125, 39.690280594818034],
[-3.58154296875, 39.757879992021756],
[-3.5595703125, 39.926588421909436],
[-3.97705078125, 39.9434364619742],
[-3.97705078125, 40.212440718286466],
[-2.57080078125, 40.195659093364654],
[-2.548828125, 39.90973623453719],
[-3.01025390625, 39.87601941962116],
[-3.01025390625, 39.554883059924016],
[-3.427734375, 39.30029918615029],
[-4.32861328125, 39.30029918615029],
[-5.185546875, 39.41922073655956],
[-5.64697265625, 39.690280594818034],
[-5.888671875, 40.06125658140474],
[-5.91064453125, 40.54720023441049],
[-5.80078125, 41.0130657870063],
[-5.47119140625, 41.32732632036622],
[-5.053710937499999, 41.47566020027821],
[-4.306640625, 41.52502957323801],
[-3.603515625, 41.44272637767212],
[-2.96630859375, 41.16211393939692],
[-2.8125, 40.81380923056958],
[-3.14208984375, 40.58058466412761],
[-3.66943359375, 40.896905775860006]]]}}],
'crs': {'type': 'name',
'properties': {'name': 'urn:ogc:def:crs:OGC:1.3:CRS84'}}}}
Query
In order to retrieve data from the datasets it is possible to send queries to the API using the SQL or Feature Service languages.
Two different endpoints are provided (under the dataset path and a generic one) and the sql query can be provided via query parameters or in the body of a POST request.
curl -i -H 'Authorization: Bearer your-token>' -H 'Content-Type: application/json' -XPOST 'http://api.skydipper.com/v1/query/<dataset_id>/' -d '{
"sql": "SELECT * FROM <dataset_id> limit 10"
}
'
curl -i -XGET http\://api.skydipper.com/v1/query\?sql\=SELECT\ \*\ from\ <dataset.slug>
Select clause
The SELECT part of the queries supports naming columns, alias, math operations, DISTINCT, COUNT, SQL functions and PostGIS functions
SELECT * FROM table
SELECT count(*) FROM table
SELECT a, b FROM table
SELECT a, count(*) FROM table
SELECT sum(int) FROM table
SELECT avg(int) FROM table
SELECT max(int) FROM table
SELECT min(int) FROM table
SELECT min(int) as minimum FROM table
SELECT ST_valueCount(rast, 1, true) FROM table
From clause
It is possible to refer to a dataset by using its table name, slug or id.
SELECT * FROM <dataset.tableName>
SELECT * FROM <dataset.slug>
SELECT * FROM <dataset.id>
Where clause
SELECT * FROM table WHERE a > 2
SELECT * FROM table WHERE a = 2
SELECT * FROM table WHERE a < 2
SELECT * FROM table WHERE a >= 2
SELECT * FROM table WHERE a = 2 and b < 2
SELECT * FROM table WHERE text like 'a%'
SELECT * FROM table WHERE st_intersects(st_setsrid(st_geomfromgeojson('{}'), 4326), the_geom)
SELECT * FROM table WHERE data BETWEEN 1 AND 3
Group by clause
It is possible to group results by column name, SQL functions and PostGIS functions. Special grouping operations are available for document-type datasets (CSV and JSON) - see this link for more info.
SELECT * FROM tablename GROUP BY columnOne
SELECT * FROM tablename GROUP BY columnOne, columnTwo
SELECT * FROM tablename GROUP BY ST_GeoHash(the_geom_point,8)
SELECT a, count(int) FROM table GROUP BY a
SELECT count(*) FROM tablename GROUP BY ST_GeoHash(the_geom, 8)
/* Only supported in document-type datasets - see https://github.com/NLPchina/elasticsearch-sql/tree/5.5.2.0#beyond-sql for full details */
SELECT COUNT(age) FROM tablename GROUP BY range(age, 20,25,30,35,40)
SELECT online FROM online GROUP BY date_histogram(field='insert_time','interval'='1d')
SELECT online FROM online GROUP BY date_range(field='insert_time','format'='yyyy-MM-dd' ,'2014-08-18','2014-08-17','now-8d','now-7d','now-6d','now')
Order by clause
It is possible to order results by column name, SQL functions and PostGIS functions
Limit and offset clause
You can specify limit and offset clauses
SELECT * FROM table limit=20
SELECT * FROM table limit=20 offset 10
Raster queries available
SELECT ST_METADATA(rast) FROM table
SELECT ST_BANDMETADATA(rast, occurrence) FROM table
SELECT ST_SUMMARYSTATS() FROM table
SELECT ST_HISTOGRAM(rast, 1, auto, true) FROM table
SELECT ST_valueCount(rast, 1, true) FROM table
Freeze query
It is possible generate a json file in a bucket of the sql result. You only need send a query param freeze with value true and you will obtain the url of the json file.
curl -i -XGET http\://api.skydipper.com/v1/query\?sql\=SELECT\ \*\ from\ <dataset.slug>&freeze=true
Download
You can download the result of a query using the download endpoint.
# The id of the dataset is part of the URL
curl -XGET https://api.skydipper.com/v1/download/<dataset.id>?sql=SELECT * from <dataset.tableName>
# The id of the dataset is in the FROM clause
curl -XGET https://api.skydipper.com/v1/download?sql=SELECT * from <dataset.id>
There are two ways to call it:
- you can either specify the id of the dataset in the URL
- or you can pass it as part of the SQL query (in the FROM clause)
You can also specify which file type you want to download (JSON or CSV), except for Google Earth Engine datasets (only JSON).
# The format is explicitly set
curl -XGET https://api.skydipper.com/v1/download/<dataset.id>?sql=SELECT * from <dataset.tableName>&format=json
curl -XGET https://api.skydipper.com/v1/download/<dataset.id>?sql=SELECT * from <dataset.tableName>&format=csv
RecentImagery
Service for identifying satellite imagery tiles from Landsat and Sentinel-2. You are able to search for a location, and time range, and set band visulisation parameters.
Return a list of all intersecting satellite images
import requests
url=f"http://api.skydipper.com/v1/recent-imagery"
params={"lat":28.399391877577933,
"lon":-16.493425662438167,
"start":"2019-11-1",
"end":"2019-11-22",
"bands":None}
r = requests.get(url,params=params)
print(r.json())
Returns a response like:
{'data': {'id': None,
'tiles': [{'attributes': {'bbox': {'geometry': {'coordinates': [[-15.92558389724579,
28.925190549257714],
[-15.92559671449868, 28.925191163600214],
[-17.051433713664156, 28.91274387174152],
[-17.051480391568088, 28.912706620290745],
[-17.051531935518994, 28.912674682697084],
[-17.05153490920881, 28.91265990682834],
[-17.041910802259004, 28.41750963441286],
[-17.032527124641494, 27.922327989157285],
[-17.03248495569906, 27.922287141116684],
[-17.032448913873885, 27.92224196307347],
[-17.0324320643225, 27.922239418847433],
[-15.917013741784361, 27.934185520299348],
[-15.916967046088413, 27.93422235347645],
[-15.91691560017191, 27.934253830965012],
[-15.916912552853256, 27.93426863344697],
[-15.921148642190191, 28.429707339526168],
[-15.925493100926781, 28.92510186499591],
[-15.925535317176289, 28.925143044864797],
[-15.925571259256028, 28.925188529207674],
[-15.92558389724579, 28.925190549257714]],
'type': 'Polygon'}},
'cloud_score': 57.3898,
'date_time': '2019-11-17 11:52:21Z',
'instrument': 'Sentinel-2A',
'source': 'COPERNICUS/S2/20191117T115221_20191117T115220_T28RCS',
'thumbnail_url': None,
'tile_url': 'https://earthengine.googleapis.com/map/6c4d08f0e527f62e97d85a92c5c181bc/{z}/{x}/{y}?token=733263c1e4925c385702d2a18f2e39a6'
}}]
}
}
Request tiles
You can use the response from the query to /recent-imagery to make a further request to tiles and thumbs endpoints.
import requests
tiles_url = "http://api.skydipper.com/v1/recent-imagery/tiles"
body={"source_data": [{"source":'COPERNICUS/S2/20191107T115221_20191107T115221_T28RCS'},{"source":'LANDSAT/LC08/C01/T1_RT_TOA/LC08_207040_20191117'}],
"min": None,
"max": None,
"opacity": 1.0,
"bands": None}
r = requests.post(tiles_url, json=body)
print(r.json())
Which will result in a response such as:
{'data': {'attributes': [{'source_id': 'COPERNICUS/S2/20191107T115221_20191107T115221_T28RCS',
'tile_url': 'https://earthengine.googleapis.com/map/d58d121e0a14ccf17bb3fa08af87bb73/{z}/{x}/{y}?token=3fb09853e976ad45cfc4b3dc267f455a'},
{'source_id': 'LANDSAT/LC08/C01/T1_RT_TOA/LC08_207040_20191117',
'tile_url': 'https://earthengine.googleapis.com/map/277080042a8a4c5481346a3f341ed01a/{z}/{x}/{y}?token=613fe7ab781cde1fbca1e1b242c508aa'}],
'id': None,
'type': 'recentimages-tiles'}}
Request thumbnails
import requests
tiles_url = "http://api.skydipper.com/v1/recent-imagery/thumbs"
body={"source_data": [{"source":'COPERNICUS/S2/20191107T115221_20191107T115221_T28RCS'},{'source': 'COPERNICUS/S2/20191117T115221_20191117T115220_T28RCS'}, {"source":'LANDSAT/LC08/C01/T1_RT_TOA/LC08_207040_20191117'}],
"min": None,
"max": None,
"opacity": 1.0,
"bands": None}
r = requests.post(tiles_url, json=body)
print(r.json())
{'data': {'attributes': [{'source': 'COPERNICUS/S2/20191107T115221_20191107T115221_T28RCS',
'thumbnail_url': 'https://earthengine.googleapis.com/api/thumb?thumbid=ba7e8eb6d9606ad6191402148fc2e4dd&token=d732ad356760313627096ed9888944f4'},
{'source': 'COPERNICUS/S2/20191117T115221_20191117T115220_T28RCS',
'thumbnail_url': 'https://earthengine.googleapis.com/api/thumb?thumbid=caa55e2a982081b793c99dc95a7ca3d5&token=943827c8075eb9b3960bf95ee304b57a'},
{'source': 'LANDSAT/LC08/C01/T1_RT_TOA/LC08_207040_20191117',
'thumbnail_url': 'https://earthengine.googleapis.com/api/thumb?thumbid=8af65bde5696bd2189a225a7dff5d346&token=6087176665a1bbbe72604b810f72f308'}],
'id': None,
'type': 'recentimages-thumbs'}}
User Management
The following endpoints expose the API’s functionality regarding user management. For more information or implementation details, see the source code.
Login (email + password)
Login endpoints support both HTML and JSON output formats, depending on the Content-type provided in the request. Keep in mind that HTML-based requests will result in redirects - for example, after successfully logging in, you will be taken to /auth/success - while JSON based requests will simply return the matching HTTP code - 200 in case of a successful login.
GET <BASE API URL>/auth/
Convenience URL that redirects to <BASE API URL>/auth/login
GET <BASE API URL>/auth/login
Basic API auth login page. Only supported for HTML requests.
POST <BASE API URL>/auth/login
Endpoint for email + password based login.
For HTML requests, it will redirect to either <BASE API URL>/auth/success or <BASE API URL>/auth/fail depending on whether the login was successful or not. An optional callbackUrl query parameter can be provided, in which case the user will be redirected to that URL in case of login success.
For JSON requests, it will return 200 or 401 HTTP response code depending on whether the login was successful or not. In case of successful logins, the basic user details will be returned as a JSON object.
# Email + password based login - JSON format
curl -X POST http://api.skydipper.com/auth/login \
-H "Content-Type: application/json" -d \
'{
"email":"your-email@provider.com",
"password":"potato"
}'
// Response:
{
"data": {
"email": "your-email@provider.com",
"createdAt": "2018-11-15T04:46:35.313Z",
"role": "USER",
"extraUserData": {
"apps": [
"skydipper"
]
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjViZWNmYTJiNjdkYTBkM2VjMDdhMjdmNiIsInJvbGUiOiJVU0VSIiwicHJvdmlkZXIiOiJsb2NhbCIsImVtYWlsIjoidGVzdEBleGFtcGxlLmNvbSIsImV4dHJhVXNlckRhdGEiOnsiYXBwcyI6WyJydyJdfSwiY3JlYXRlZEF0IjoxNTQzMzE1NzMxNzcwLCJpYXQiOjE1NDMzMTU3MzF9.kIdkSOb7mCMOxE2ipqVOBrK7IefAjLDhaPG9DT1qvCw"
}
}
GET <BASE API URL>/auth/fail
Displays login errors for HTML requests. Not supported on JSON requests.
GET <BASE API URL>/auth/check-logged
Check login status
GET <BASE API URL>/auth/success
Successful login page for HTML requests. Not supported on JSON requests.
GET <BASE API URL>/auth/logout
Login invalidation endpoint
GET <BASE API URL>/auth/generate-token
Generates a JWT token for the current user session.
Login (3rd party oauth)
- GET ’
/auth/twitter’ - Starts authentication using the configured Twitter settings - GET ’
/auth/twitter/callback’ - Callback used once Twitter auth is done - GET ’
/auth/google’ - Starts authentication using the configured Google settings - GET ’
/auth/google/callback’ - Callback used once Google auth is done - GET ’
/auth/google/token’ - Endpoint that expects the Google token used by the API to validate the user session. - GET ’
/auth/facebook’ - Starts authentication using the configured Google settings - GET ’
/auth/facebook/callback’ - Callback used once Facebook auth is done - GET ’
/auth/facebook/token’ - Endpoint that expects the Facebook token used by the API to validate the user session.
Registration
Registration endpoints support both HTML and JSON output formats, depending on the Content-type provided in the request.
GET <BASE API URL>/auth/sign-up
Account creation page, for accounts using email + password based login for HTML requests. Not supported on JSON requests.
POST <BASE API URL>/auth/sign-up
Account creation endpoint, for accounts using email + password based login for both HTML and JSON requests.
For HTML requests, it will display a message informing about any validation error, or informing the user in case of success.
For JSON requests, it will return 200 or 422 HTTP response code depending on whether the login was successful or not. In case of successful logins, the basic user details will be returned as a JSON object. In case of failure, an array of errors is returned.
While optional, it’s highly recommended that you specify which apps the user will be granted access to, as most API operation validate the user’s apps match datasets, widgets, etc.
# Account creation using email + password
curl -X POST http://api.skydipper.com/auth/sign-up \
-H "Content-Type: application/json" -d \
'{
"email":"your-email@provider.com",
"password":"potato",
"repeatPassword":"potato",
"apps": ["skydipper"]
}'
// Response:
{
"data": {
"id": "5bfd237767b3176dd63f2eb7",
"email": "your-email@provider.com",
"createdAt": "2018-11-27T10:59:03.531Z",
"role": "USER",
"extraUserData": {
"apps": ["skydipper"]
}
}
}
GET <BASE API URL>/auth/confirm/:token
Endpoint used in the user validation email to confirm the address upon registration.
It accepts an optional callbackUrl query parameter with an URL to which the user will be redirect if the confirmation succeeds.
Should no callbackUrl be provided, the user is redirected to an URL based on the first application associated to their user account - see ct-oauth-plugin configuration for more info.
Should that application have no configured redirect URL, or the user have no configured app, they are redirect to a platform-wide default URL - see ct-oauth-plugin configuration for more info.
Password recovery
Password recovery endpoints support both HTML and JSON output formats, depending on the Content-type provided in the request.
GET <BASE API URL>/auth/reset-password
Displays the password reset form page.
POST <BASE API URL>/auth/reset-password
Endpoint where the password reset request is sent.
# Password reset
curl -X POST http://api.skydipper.com/auth/reset-password \
-H "Content-Type: application/json" -d \
'{
"email":"your-email@provider.com"
}'
GET <BASE API URL>/auth/reset-password/:token
Endpoint used to validate email address upon password reset request.
POST <BASE API URL>/auth/reset-password/:token
Endpoint used to submit the new password.
# New password submission
curl -X POST http://api.skydipper.com/auth/reset-password/<email token> \
-H "Content-Type: application/json" -d \
'{
"password":"potato",
"repeatPassword":"potato"
}'
User details management
GET <BASE API URL>/auth/user
Lists user accounts:
- Only users with role ADMIN have permissions to use this endpoint.
- Email+password based accounts that have not had their email address confirmed will not be listed by this endpoint.
- Only users belonging to the same apps as the requesting user will be shown.
This endpoint supports the following optional filter params:
- name
- provider
- role
# Lists all currently active users belonging to the same apps as the requester
curl -X GET http://api.skydipper.com/auth/user
-H "Content-Type: application/json" -d \
-H "Authorization: Bearer <your-token>" \
# User listing, filter by email address
curl -X GET http://api.skydipper.com/auth/user?email=my.address@email.com
-H "Content-Type: application/json" -d \
-H "Authorization: Bearer <your-token>" \
GET <BASE API URL>/auth/user/:id
# shows info for user with the given id
curl -X GET http://api.skydipper.com/auth/user/<user_id>
-H "Content-Type: application/json" -d \
-H "Authorization: Bearer <your-token>" \
PATCH <BASE API URL>/auth/user/me
- Updates current user details.
- Can be used by any user.
- Supported fields:
name,photoandemail(except on 3rd party auth) - Returns the new state of the updated user object.
# updates current user details
curl -X PATCH http://api.skydipper.com/auth/user/me
-H "Content-Type: application/json" -d \
-H "Authorization: Bearer <your-token>" \
'{
"name":"new-name",
"photo": "https://an.image.url/photo.jpg",
...
}'
PATCH <BASE API URL>/auth/user/:id
- Updates specified user details.
- Can only be used by admins.
- Supported fields:
name,photoandemail(except on 3rd party auth) - Returns the new state of the updated user object.
# updates details of user given its id
curl -X PATCH http://api.skydipper.com/auth/user/<user_id>
-H "Content-Type: application/json" -d \
-H "Authorization: Bearer <your-token>" \
'{
"name":"new-name",
"photo": "https://an.image.url/photo.jpg",
...
}'
DELETE <BASE API URL>/auth/user/:id
- Deletes the specified user account.
- Can only be used by admins.
- Returns the deleted user object.
# updates details of user given its id
curl -X DELETE http://api.skydipper.com/auth/user/<user_id>
-H "Content-Type: application/json" -d \
-H "Authorization: Bearer <your-token>" \
'{
"name":"user name",
"email":"user@email.com",
"photo": "https://an.image.url/photo.jpg",
...
}'
Errors
The Skydipper API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request – Your request is incomplete or contains errors |
| 401 | Unauthorized – Your API key is incorrect |
| 403 | Forbidden – The kitten requested is hidden for administrators only |
| 404 | Not Found – The specified kitten could not be found |
| 405 | Method Not Allowed – You tried to access a kitten with an invalid method |
| 406 | Not Acceptable – You requested a format that is not json |
| 410 | Gone – The kitten requested has been removed from our servers |
| 429 | Too Many Requests – You’re requesting too many kittens! Slow down! |
| 500 | Internal Server Error – We had a problem with our server. Try again later. |
| 503 | Service Unavailable – We’re temporarily offline for maintenance. Please try again later. |
API attribution requirements
By using the Skydipper API, you agree to the Skydipper terms of service and attribution requirements.