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 are created, queued, init, tiles, process, complete and error.
  • 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 is true.
  • 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 is 1.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 result
  • csv 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.