API docs by Redocly

Insula APIs (2.0)

Download OpenAPI specification:Download

collections

Platform collection related operations. A collection is a container for files of a certain type.

Get platform collections.

Authorizations:
oauth2Password
query Parameters
projection
string
Default: "shortCollection"
Enum: "shortCollection" "detailedCollection"

The collection projection. Determines the schema of the search results

page
integer >= 0
Default: 0

The pagination page number.

size
integer >= 0
Default: 20

The number of items per page.

Responses

Response samples

Content type
application/json
{
  • "page": {
    },
  • "_embedded": {
    }
}

Create a platform collection

Authorizations:
oauth2Password
Request Body schema: application/json
required

The collection metadata. Regarding the 'fileType' field, use:

  • REFERENCE_DATA: For a collection where local data can be uploaded through the platformFiles APIs
  • OUTPUT_PRODUCT: For collection used for storing the results of a processing
name
required
string (Collection name)
description
string (Collection description)
fileType
required
string (Platform file type)
Enum: "REFERENCE_DATA" "OUTPUT_PRODUCT" "EXTERNAL_PRODUCT" "REMOTE_DATA"

The platform file type.

  • REFERENCE_DATA indicates user uploaded data.
  • OUTPUT_PRODUCT indicates processing outputs.
productsType
string (Collection product types)

Define the type of products contained in the collections. A free text field that can be used for filtering in search

Responses

Request samples

Content type
application/json
{
  • "name": "My Collection",
  • "fileType": "REFERENCE_DATA",
  • "productsType": "mixed"
}

Response samples

Content type
application/json
{}

Get collection metadata.

Authorizations:
oauth2Password
path Parameters
collectionId
required
integer (Platform identifier) >= 1

Collection ID

query Parameters
projection
string
Default: "shortCollection"
Enum: "shortCollection" "detailedCollection"

The collection projection. Determines the schema of the search results

Responses

Response samples

Content type
application/json
Example
{
  • "name": "string",
  • "description": "string",
  • "fileType": "REFERENCE_DATA",
  • "productsType": "string",
  • "id": 1,
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364",
  • "owner": {
    }
}

Update a platform collection

Authorizations:
oauth2Password
path Parameters
collectionId
required
integer (Platform identifier) >= 1

Collection ID

Request Body schema: application/json
required

The collection metadata.

name
string (Collection name)
description
string (Collection description)
productsType
string (Collection product types)

Define the type of products contained in the collections. A free text field that can be used for filtering in search

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "productsType": "string"
}

Response samples

Content type
application/json
{}

Delete platform collection

Authorizations:
oauth2Password
path Parameters
collectionId
required
integer (Platform identifier) >= 1

Collection ID

Responses

Response samples

Content type
application/json
{
  • "status_code": 401,
  • "status": "Unauthorized"
}

Search for platform collections.

Allow to search for platform collections by text, file type, product type, owner

Authorizations:
oauth2Password
query Parameters
filter
string

The search string

fileType
string (Platform file type)
Enum: "REFERENCE_DATA" "OUTPUT_PRODUCT" "EXTERNAL_PRODUCT" "REMOTE_DATA"

The collection file type

productsType
Array of strings

A list of collection product types

notProductsType
Array of strings

A list of collection product types to omit from the result

projection
string
Default: "shortCollection"
Enum: "shortCollection" "detailedCollection"

The collection projection. Determines the schema of the search results

owner
string <uri> (Resource owner) ^https://foodsecurity-explorer.insula.earth/s...

The owner of the resource. Must be provided as a reference uri in the form of https://foodsecurity-explorer.insula.earth/secure/api/v2.0/users/{userId}

notOwner
string <uri-template> ^https://foodsecurity-explorer.insula.earth/s...

Show all resources not owned by a user. Must be provided as a reference uri in the form of https://foodsecurity-explorer.insula.earth/secure/api/v2.0/users/{userId}

page
integer >= 0
Default: 0

The pagination page number.

size
integer >= 0
Default: 20

The number of items per page.

Responses

Response samples

Content type
application/json
{
  • "page": {
    },
  • "_embedded": {
    }
}

platformFiles

Platform files related operations.

Get platform files.

Authorizations:
oauth2Password
query Parameters
projection
string
Default: "shortPlatformFile"
Enum: "shortPlatformFile" "detailedPlatformFile"

The platform file output projection. Determines the schema of the search results

page
integer >= 0
Default: 0

The pagination page number.

size
integer >= 0
Default: 20

The number of items per page.

Responses

Response samples

Content type
application/json
{
  • "page": {
    },
  • "_embedded": {
    }
}

Get platform file metadata.

Authorizations:
oauth2Password
path Parameters
platformFileId
required
integer (Platform identifier) >= 1

Platoform file ID

query Parameters
projection
string
Default: "shortPlatformFile"
Enum: "shortPlatformFile" "detailedPlatformFile"

The platform file output projection. Determines the schema of the search results

Responses

Response samples

Content type
application/json
Example
{
  • "filename": "string",
  • "restoId": "68861567-43d0-43a6-910a-04c0f89bc81a",
  • "type": "REFERENCE_DATA",
  • "id": 1,
  • "owner": {
    }
}

Delete platform file

Authorizations:
oauth2Password
path Parameters
platformFileId
required
integer (Platform identifier) >= 1

Platform file ID

Responses

Response samples

Content type
application/json
{
  • "status_code": 401,
  • "status": "Unauthorized"
}

Download platform file.

Authorizations:
oauth2Password
path Parameters
platformFileId
required
integer (Platform identifier) >= 1

Platoform file ID

Responses

Response samples

Content type
application/octet-stream
Get platform file collection. 
Authorizations:
oauth2Password
path Parameters
platformFileId
required
integer (Platform identifier)   >= 1 
 
Platoform file ID


query Parameters
projection
string
 Default:  "shortCollection"
 Enum: "shortCollection" "detailedCollection" 
 
The collection projection. Determines the schema of the search results


Responses
 Response samples 
Content type
application/json
Example
{
  • "name": "string",
  • "description": "string",
  • "fileType": "REFERENCE_DATA",
  • "productsType": "string",
  • "id": 1,
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364",
  • "owner": {
    }
}
Get platform file processing jobs. 
Authorizations:
oauth2Password
path Parameters
platformFileId
required
integer (Platform identifier)   >= 1 
 
Platoform file ID


query Parameters
projection
string
 Default:  "shortJob"
 Enum: "shortJob" "detailedJob" 
 
The job projection. Determines the schema of the search results


Responses
 Response samples 
Content type
application/json
{
  • "_embedded": {
    }
}
Upload a platform file into a reference collection 
Authorizations:
oauth2Password
Request Body schema: multipart/form-data
collection
required
string <uuid> 
 
the target collection catalogue identifier (i.e. the 'identifier' field in Collection metadata)


fileType
required
string (Platform file upload type) 
 Enum: "GEOTIFF" "SHAPEFILE" "MOSAIC" "OTHER" 
 
The upload file type.


    

  • GEOTIFF: Geotiff file. It shall be in COG (Cloud Optimized Geotiff) format. A WMS layer will be created for data visualization.
    • 

  • SHAPEFILE: Shapefile. The file shall be a zip archive containing
in the root folder the set of shapefile inputs
('shp', 'dbf', 'shx' and 'prj' as a minimum). A WFS layer will be created
allowing access to the underlying data, and a WMS layer for its visualization.
    • 

  • MOSAIC: Geotiff mosaic. The product shall be in COG (Cloud Optimized Geotiff) format and 
will be added to a time-enabled raster coverage (WMS layer).
The filename must include the time in ISO 8601 basic format `YYYYMMDDThhmmssZ' (e.g. 20100101T000000Z ).
All files of the collection will be ingested in the same raster coverage (WMS layer) and shall have the same bands configuration.
    • 

  • OTHER: Other file type. It won't be associated to any visualization
    • 



file
required
string <binary> 
 
The file content


object
 
Additional metadata


Responses
 Response samples 
Content type
application/json
{}
Search for platform files. 
Allow to search for platform files by text, collection, file type, job and/or owner


Authorizations:
oauth2Password
query Parameters
filter
string
 
The search string


type
string (Platform file type) 
 Enum: "REFERENCE_DATA" "OUTPUT_PRODUCT" "EXTERNAL_PRODUCT" "REMOTE_DATA" 
 
The collection file type


collection
string <uri> ^https://foodsecurity-explorer.insula.earth/s...
 
The parent collection. Must be provided as a reference uri in the form of https://foodsecurity-explorer.insula.earth/secure/api/v2.0/collections/{collectionId}


job
string <uri> ^https://foodsecurity-explorer.insula.earth/s...
 
The job that generated the file. Must be provided as a reference uri in the form of https://foodsecurity-explorer.insula.earth/secure/api/v2.0/jobs/{jobId}


projection
string
 Default:  "shortPlatformFile"
 Enum: "shortPlatformFile" "detailedPlatformFile" 
 
The platform file output projection. Determines the schema of the search results


owner
string <uri>  (Resource owner) ^https://foodsecurity-explorer.insula.earth/s...
 
The owner of the resource. Must be provided as a reference uri in the form of https://foodsecurity-explorer.insula.earth/secure/api/v2.0/users/{userId}


notOwner
string <uri-template> ^https://foodsecurity-explorer.insula.earth/s...
 
Show all resources not owned by a user. Must be provided as a reference uri in the form of https://foodsecurity-explorer.insula.earth/secure/api/v2.0/users/{userId}


page
integer  >= 0 
 Default:  0
 
The pagination page number.


size
integer  >= 0 
 Default:  20
 
The number of items per page.


sort
string^[a-zA-Z]+(,(asc|desc))?$
 
The query sort parameter. It should be provided as the parameter name to sort by, optionally followed by a comma and the 'asc' or 'desc' keyword


Responses
 Response samples 
Content type
application/json
{
  • "page": {
    },
  • "_embedded": {
    }
}
jobs
Processing jobs related operations.


Get processing job configs. 
Authorizations:
oauth2Password
query Parameters
page
integer  >= 0 
 Default:  0
 
The pagination page number.


size
integer  >= 0 
 Default:  20
 
The number of items per page.


Responses
 Response samples 
Content type
application/json
{
  • "page": {
    },
  • "_embedded": {
    }
}
Create a processing job configuration 
Create the configuration for a processing job. This is the first step required to launch a processing job


Authorizations:
oauth2Password
Request Body schema: application/json
required
The processing job configuration parameters


required
object (Job processing inputs) 
 
service
required
string <uri>  (Service) ^https://foodsecurity-explorer.insula.earth/s...
 
The service to run. It should be a reference URI in the form
https://foodsecurity-explorer.insula.earth/secure/api/v2.0/services/{serviceId}


label
string (Label) 
 
An optional label to give to the processing job


Responses
 Request samples 
Content type
application/json
{
  • "inputs": {
    },
  • "service": "https://foodsecurity-explorer.insula.earth/secure/api/v2.0/services/66",
  • "label": "string"
}
 Response samples 
Content type
application/json
{
  • "id": 1,
  • "inputs": {
    },
  • "label": "string",
  • "_embedded": {
    },
  • "_links": {}
}
Get processing job config metadata. 
Authorizations:
oauth2Password
path Parameters
jobConfigId
required
integer (Platform identifier)   >= 1 
 
Job config ID


Responses
 Response samples 
Content type
application/json
{
  • "id": 1,
  • "inputs": {
    },
  • "label": "string",
  • "_embedded": {
    },
  • "_links": {}
}
Delete a job config 
Authorizations:
oauth2Password
path Parameters
jobConfigId
required
integer (Platform identifier)   >= 1 
 
Job config ID


Responses
 Response samples 
Content type
application/json
{
  • "status_code": 401,
  • "status": "Unauthorized"
}
Launch a processing job. 
Authorizations:
oauth2Password
path Parameters
jobConfigId
required
integer (Platform identifier)   >= 1 
 
Job config ID


Responses
 Response samples 
Content type
application/json
{
  • "extId": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "status": "CREATED",
  • "queuePosition": 0,
  • "parent": true,
  • "guiUrl": "http://example.com",
  • "stage": "string",
  • "phase": "CREATED"
}
Get processing jobs. 
Authorizations:
oauth2Password
query Parameters
projection
string
 Default:  "shortJob"
 Enum: "shortJob" "detailedJob" 
 
The job projection. Determines the schema of the search results


page
integer  >= 0 
 Default:  0
 
The pagination page number.


size
integer  >= 0 
 Default:  20
 
The number of items per page.


Responses
 Response samples 
Content type
application/json
{
  • "page": {
    },
  • "_embedded": {
    }
}
Get processing job metadata. 
Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


query Parameters
projection
string
 Default:  "shortJob"
 Enum: "shortJob" "detailedJob" 
 
The job projection. Determines the schema of the search results


Responses
 Response samples 
Content type
application/json
Example
{
  • "extId": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "status": "CREATED",
  • "queuePosition": 0,
  • "parent": true,
  • "guiUrl": "http://example.com",
  • "stage": "string",
  • "phase": "CREATED",
  • "id": 1,
  • "owner": {
    },
  • "serviceName": "string",
  • "label": "string",
  • "systematicParameter": "string"
}
Get processing job config. 
Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


Responses
 Response samples 
Content type
application/json
{
  • "id": 1,
  • "inputs": {
    },
  • "label": "string",
  • "_embedded": {
    },
  • "_links": {}
}
Get processing job logs. 
Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


Responses
 Response samples 
Content type
application/json
[
  • {
    }
]
Retrieve processing job outputs. 
Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


query Parameters
projection
string
 Default:  "shortPlatformFile"
 Enum: "shortPlatformFile" "detailedPlatformFile" 
 
The platform file output projection. Determines the schema of the search results


Responses
 Response samples 
Content type
application/json
{
  • "_embedded": {
    }
}
Get processing job parent. 
Retrieve the processing job parent. Applicable only to child jobs 
(subtasks of a PARALLEL_PROCESSOR service or of a systematic processing)


Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


query Parameters
projection
string
 Default:  "shortJob"
 Enum: "shortJob" "detailedJob" 
 
The job projection. Determines the schema of the search results


Responses
 Response samples 
Content type
application/json
Example
{
  • "extId": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "status": "CREATED",
  • "queuePosition": 0,
  • "parent": true,
  • "guiUrl": "http://example.com",
  • "stage": "string",
  • "phase": "CREATED",
  • "id": 1,
  • "owner": {
    },
  • "serviceName": "string",
  • "label": "string",
  • "systematicParameter": "string"
}
Get processing job subjobs. 
Retrieve the list of subjobs. Applicable only to parent jobs 
(associated to a PARALLEL_PROCESSOR service or to a systematic processing)


Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


query Parameters
projection
string
 Default:  "shortJob"
 Enum: "shortJob" "detailedJob" 
 
The job projection. Determines the schema of the search results


Responses
 Response samples 
Content type
application/json
{
  • "_embedded": {
    }
}
Cancel processing job. 
Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


Responses
 Response samples 
Content type
application/json
{
  • "status_code": 401,
  • "status": "Unauthorized"
}
Retry failed processing job. 
Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


Responses
 Response samples 
Content type
application/json
{
  • "status_code": 401,
  • "status": "Unauthorized"
}
Terminate processing job. 
Terminate a running interactive application. Applicable only to job associated to APPLICATION services.


Authorizations:
oauth2Password
path Parameters
jobId
required
integer (Platform identifier)   >= 1 
 
Processing job ID


Responses
 Response samples 
Content type
application/json
{
  • "status_code": 401,
  • "status": "Unauthorized"
}
Search for processing jobs. 
Allow to search for processing jobs


Authorizations:
oauth2Password
query Parameters
filter
string
 
The search string


status
Array of strings (Job status) 
Items Enum: "CREATED" "PENDING" "RUNNING" "COMPLETED" "ERROR" "CANCELLED" "WAITING" "CONDITION_WAIT" 
 
A list of job states


parentId
integer (Platform identifier)   >= 1 
 
Parent job ID. Retrieve subjobs of the job with the provided ID.
If omitted only non subjobs jobs (parent jobs or childless jobs) are returned


startDateTime
string <date-time> 
 
Job start date


endDateTime
string <date-time> 
 
Job end date


inputIdentifier
string
 
Input identifier. Search for jobs where one of the inputs matches the provided string


projection
string
 Default:  "shortJob"
 Enum: "shortJob" "detailedJob" 
 
The job projection. Determines the schema of the search results


owner
string <uri>  (Resource owner) ^https://foodsecurity-explorer.insula.earth/s...
 
The owner of the resource. Must be provided as a reference uri in the form of https://foodsecurity-explorer.insula.earth/secure/api/v2.0/users/{userId}


notOwner
string <uri-template> ^https://foodsecurity-explorer.insula.earth/s...
 
Show all resources not owned by a user. Must be provided as a reference uri in the form of https://foodsecurity-explorer.insula.earth/secure/api/v2.0/users/{userId}


page
integer  >= 0 
 Default:  0
 
The pagination page number.


size
integer  >= 0 
 Default:  20
 
The number of items per page.


sort
string^[a-zA-Z]+(,(asc|desc))?$
 
The query sort parameter. It should be provided as the parameter name to sort by, optionally followed by a comma and the 'asc' or 'desc' keyword


Responses
 Response samples 
Content type
application/json
{
  • "page": {
    },
  • "_embedded": {
    }
}
search
Catalogue search.


Search for catalogue products 
Perform a catalogue search.


Authorizations:
oauth2Password
query Parameters
catalogue
required
string
  Examples: 
  • catalogue=REF_DATA - User uploaded data
  • catalogue=PLATFORM_PRODUCTS - Processing outputs
  • catalogue=SATELLITE - Copernicus EO data
The query catalogue


collection
string
 
The processing output collection identifier.
Mandatory if the catalogue parameter is set to PLATFORM_PRODUCTS. Unused otherwise


refDataCollection
string
 
The reference collection identifier.
Mandatory if the catalogue parameter is set to REF_DATA. Unused otherwise


aoi
string <wkt> 
 
The area of interest, expressed as a WKT polygon string.


productDateStart
string <date-time> 
 
The product start date


productDateEnd
string <date-time> 
 
The product end date


identifier
string
 
The product identifier


object
 
 Example:  additionalParam1=additionalValue1&additionalParam2=additionalValue2
Additional query parameters.
The full list of available query parameters can be retrieved from the search/parameters endpoint.


resultsPerPage
integer
 Default:  20
 
Page size


page
integer  >= 0 
 Default:  0
 
The pagination page number.


Responses
 Response samples 
Content type
application/json
{
  • "page": {
    },
  • "features": [
    ]
}
Retrieve search parameters 
Retrieve description of available search parameters


Authorizations:
oauth2Password
query Parameters
resolveAll
boolean
 Default:  true
 
If set to false, it will prevent expanding all dynamic parameters (e.g. select options), providing a faster response


Responses
 Response samples 
Content type
application/json
{
  • "catalogue": {
    },
  • "identifier": {
    },
  • "aoi": {
    }
}
Retrieve dynamic search parameter values 
Retrieve allowed values for search parameter of dynamic type


Authorizations:
oauth2Password
path Parameters
parameterId
required
string
 
Dynamic parameter ID


Responses
 Response samples 
Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "onlyIf": {
    },
  • "required": true,
  • "type": "select",
  • "allowed": {
    },
  • "defaultValue": "string"
}
Retrieve additional search parameters for a specific selection 
Retrieve additional search parameters available for a specific option of a select type parameter.
Check the parameterName option tag in the Catalogue select parameter schema.


Authorizations:
oauth2Password
path Parameters
parameterName
required
string
 
Dynamic parameter name


Responses
 Response samples 
Content type
application/json
{
  • "catalogue": {
    },
  • "identifier": {
    },
  • "aoi": {
    }
}