Listing datasets
The API only allows quering a single dataset at a time. To obtain a list of valid datasets to query, send an HTTP GET
to the list-datasets
endpoint:
GET https://insar.ngu.no/insar-api/list-datasets
Parameters
The request has no parameters.
Response
If successful, the response has HTTP response code 200 and contains a JSON array enumerating the datasets. Each item in the array is a JSON object with the following fields:
name
string The dataset's short name, used when querying the dataset.displayName
string The dataset's human readable name, suitable for use in user interfaces.attribution
string Attribution for the dataset, or additional information.
Example response:
[
{
"attribution": "2015-2019",
"displayName": "Sentinel-1 Ascending 1",
"name": "in-asc1-v20a"
},
{
"attribution": "2015-2019",
"displayName": "Sentinel-1 Descending 1",
"name": "in-dsc1-v20a"
}
]
Creating a query
A query to download full resolution InSAR data is created by sending an HTTP POST
request to the query
endpoint:
POST https://insar.ngu.no/insar-api/<dataset>/query?bbox=<bounding box>
Parameters
The request has two parameters:
dataset
A valid dataset name.bbox
A bounding box. The bounding box is specified as two longitude-latitude (note the ordering) pairs:bbox=20.1404,69.3438,20.1827,69.3293
.
Valid datasets
Use a valid dataset name obtained by querying the list-datasets
endpoint. At the time of writing, the valid datasets are:
in-asc1-v20a
(Sentinel-1 Ascending 1)in-asc2-v20a
(Sentinel-1 Ascending 2)in-asc3-v20a
(Sentinel-1 Ascending 3)in-dsc1-v20a
(Sentinel-1 Descending 1)in-dsc2-v20a
(Sentinel-1 Descending 2)in-dsc3-v20a
(Sentinel-1 Descending 3)
Response
If successful, the response has HTTP response code 200 and contains a JSON object. The JSON object contains a query ID which is used when checking the state of the query or downloading results:
{ "id" : "query id" }
A successful response indicates that the server has received the query. You can now poll the server at regular intervals to determine when the query has finished executing.
Checking the state of a query
Once a query has been started, the state of the query can be inspected by making an HTTP GET
request to the query-state
endpoint at regular intervals:
GET https://insar.ngu.no/insar-api/query-state?id=<query id>
Parameters
The request has a single parameter:
query id
string The query ID to get state for
Response
A successful response (HTTP response code 200) contains a JSON object describing the current state of the query. The JSON object contains the following keys:
id
string The case-sensitive query ID.state
string The current state of the query. Possible values arecreated
,queued
,init
,tiles
,process
,complete
anderror
.duration
float The amount of time the query has been queued or running for.progress
float A value between 0 and 1 indicating the progress of the query.complete
boolean The query has finished when this flag istrue
.messages
array An array of messages from the query processor. The most recent message is the last item in the array.version
string The version of the state object. The current version is1.0.0
.
Once the query starts executing, the following additional fields are included:
dataset
string The dataset specified by the client.bbox
string The bounding box specified by the client.started
float A UTC timestamp taken when the query started executing.updated
float A UTC timestamp taken when the query state was last updated.expires
float A UTC timestamp. The query and its associated data are removed when the current time exceeds this timestamp. Currently, queries expire one hour after completion.pid
integer The process ID handling the query.num_points
integer Total number of points processed so far. On completion, the total number of points in the result set.csv
array When the query is complete, this array contains a list of files that comprise the query's result set.
If the HTTP response code is 404 (not found), the query has expired or was dropped by the server due to resource constraints.
Query states
State | Description |
---|---|
created |
The query has been received by the server |
queued |
The query is currently queued, and will start executing once a slot becomes available |
init |
The query has started executing, and is currently initializing |
tiles |
The tiles required for executing the query are being determined |
process |
The timeseries for each point are being gathered |
error |
The query stopped with an error. Inspect the messages field to determine the cause of the error. |
complete |
The query completed successfully. |
Example state object for a queued query
{
"id" : "f0faedc9e5ab468e98bd2d7ab5cf4ddb",
"state" : "queued",
"duration" : 1.234,
"messages" : ["Queued"],
"progress" : 0.0,
"complete" : false
}
Example state object for a completed query
{
"bbox": "20.1404,69.3438,20.1827,69.3293",
"complete": true,
"csv": [
"160-IW1-414-in-asc1-v20a.csv.gz",
"160-IW2-414-in-asc1-v20a.csv.gz"
],
"dataset": "in-asc1-v20a",
"duration": 6.7976908683776855,
"expires": 1579180736.818524,
"id": "f0faedc9e5ab468e98bd2d7ab5cf4ddb",
"messages": [
"Query initializing",
"Determining overlapping tiles",
"Got 5 tiles",
"Approximately 81920 points to store",
"Processing tile 1 of 5",
"Got 1525 points",
"Tile contains points from 2 different sets",
"Stored 922 points to 160-IW1-414-in-asc1-v20a.csv.gz",
"Stored 603 points to 160-IW2-414-in-asc1-v20a.csv.gz",
"Stored data from 2 different sets",
"Finished tile 1 of 5",
"Processing tile 2 of 5",
"Got 714 points",
"Tile contains points from 2 different sets",
"Stored 661 points to 160-IW1-414-in-asc1-v20a.csv.gz",
"Stored 53 points to 160-IW2-414-in-asc1-v20a.csv.gz",
"Stored data from 2 different sets",
"Finished tile 2 of 5",
"Processing tile 3 of 5",
"Got 367 points",
"Tile contains points from 1 different sets",
"Stored 367 points to 160-IW1-414-in-asc1-v20a.csv.gz",
"Stored data from 1 different sets",
"Finished tile 3 of 5",
"Processing tile 4 of 5",
"Got 4385 points",
"Tile contains points from 2 different sets",
"Stored 2444 points to 160-IW1-414-in-asc1-v20a.csv.gz",
"Stored 1941 points to 160-IW2-414-in-asc1-v20a.csv.gz",
"Stored data from 2 different sets",
"Finished tile 4 of 5",
"Processing tile 5 of 5",
"Got 4741 points",
"Tile contains points from 2 different sets",
"Stored 4611 points to 160-IW1-414-in-asc1-v20a.csv.gz",
"Stored 130 points to 160-IW2-414-in-asc1-v20a.csv.gz",
"Stored data from 2 different sets",
"Finished tile 5 of 5",
"All done"
],
"num_points": 11732,
"pid": 29851,
"progress": 1.0,
"started": 1579177130.020833,
"state": "complete",
"updated": 1579177136.818524,
"version": "1.0.0"
}
Downloading results
When a query is complete, the result set can be downloaded. The result set will currently remain available for one hour after completing the query. To download one of the items in the state object's csv
array, make an HTTP GET
request to the query-download
endpoint:
GET https://insar.ngu.no/insar-api/query-download?id=<query id>&csv=<csv name>
Parameters
The query-download
request has two parameters:
id
string The query ID from which to download a resultcsv
string The CSV file to download
Response
A successful request returns the data for the given CSV file. Make sure to download all the items listed by the csv
array to receive the complete result set.