adamapi 2.0.6

Python Adam API

Installation

Versioning

1. adamapi==1.0.1 , This package works only with ADAMCORE 1.
2. adamapi==2.0.6, This pachage works only with ADAMCORE 2.

Requirements

sudo apt-get install python3-venv python3-gdal gdal-bin

Install with pip

VENVNAME="adamapi"
python3 -m venv "${VENVNAME}"
PYTHONVERSION=$(ls ${VENVNAME}/lib/)
source "${VENVNAME}/bin/activate";
python3 -m pip install --upgrade pip;
pip install adamapi==2.0.1r1
ln -s "/usr/lib/python3/dist-packages/osgeo" "${VENVNAME}/lib/${PYTHONVERSION}/site-packages/osgeo"

API DEFINITIONS

This document briefly describes the ADMAPI functionalities.
The complete and interactive documentation is provided through a jupyter notebook (LINK to notebook TBP).
The ADAMAPI library is divided in 4 modules:

1. Auth --> the authorization module
2. Datasets --> to get the list of datasets
3. Search --> to get the lists of products, including associated metadata (e.g. geometry, cloud cover, orbit, tile, ...)
4. GetData --> to retrieve the product(s), including options to subset in space and time

1 - Auth

This module takes care of user authentication and authorization.
Without instancing an object of this module other components don't work.
Auth module is based on the ADAMAPI_KEY, a key that uniquelly identifies the user.

Class contructor and parameters

from adamapi import Auth
a = Auth()

Parameters:

position/keyword	mandatory	type	default	description

Public methods and parameters

• .setKey() --> To setup the ADAMAPI_KEY
  Parameters:

position/keyword	mandatory	type	default	description
0	True	str		The ADAMAPI_KEY

• .setAdamCore() --> To setup the url of the ADAM-CORE endpoint
  Parameters:

position/keyword	mandatory	type	default	description
0	True	str		The url like https://test.adamplatform.eu

• .authorize() --> to instanciate an auth object
  Parameters:

position/keyword	mandatory	type	default	description

• .getAuthToken() --> to get the authorization token
  Parameters:

position/keyword	mandatory	type	default	description

1.1 - ADAMAPI_KEY retrieval

To get the ADAMAPI_KEY, you need to access your ADAM portal and:

1. Select the "user icon" on the top right
2. Expand / click the "USERNAME"
3. Click on the "Api Key" to display your key

*Command-line ADAMAPI_KEY retrieval TBP*

1.2 - ADAMAPI_KEY setup

There are three methods to setup the ADAMAPI_KEY and the ADAM-CORE instance:

1. use the method setKey() and setAdamCore()

from adamapi import Auth
a = Auth()
a.setKey('<ADAMAPI_KEY>')
a.setAdamCore('https://test.adamplatform.eu')

2. Export two envars like

#open a Terminal and type:
export ADAMAPI_KEY='<ADAMAPI_KEY>'
export ADAMAPI_URL='https://test.adamplatform.eu'

3. create a file called .adamapirc in the user home directory with the following content

key=<ADAMAPI_KEY>
url=https://test.adamplatform.eu

1.3 - Examples

After ADAMAPI_KEY has been set up, an auth instance can be created with:

from adamapi import Auth
a = Auth()
a.authorize()

After authorize method you can retrive your autho token:

from adamapi import Auth
a = Auth()
a.authorize()
a.getAuthToken()

2 - Datasets

This module provides datasets discovery functionality.

Class contructor and parameters

from adamapi import Datasets
datasets = Datasets( a )

Parameters:

position/keyword	mandatory	type	default	description
0	True	Auth instance		The ADAMAPI authorized instance obtained in the previous section

Public methods and parameters

• .getDatasets() --> To retrieve datasets list and metadata
  Parameters:

position/keyword	mandatory	type	default	description
0	False	str		The datasetId.
page	False	numeric	0	Indicats a specific page
maxRecords	False	numeric	10	Max number of results in output.

2.1 Examples

This module can be used in 2 different ways.

1. To list all available datasets:

datasets = Datasets(a)
print(datasets.getDatasets())

2. To get detailed metadata about a specific dataset

datasets = Datasets(a)
print( datasets.getDatasets( '{{ID:DATASET}}' , page=0 , maxRecords=10 ) )

3 - Search

This module provides discovery functionality through the products available on the ADAM instance.

Class contructor and parameters

from adamapi import Search
search = Search( a )

Parameters:

position/keyword	mandatory	type	default	description
0	True	Auth instance		The ADAMAPI authorized instance obtained in section 1-Auth

Public methods and parameters

• .getProducts() --> To retrieve datasets list and metadata
  

Parameters:

position/keyword	mandatory	type	default	description
0	True	str		The datasetId.
maxRecords	False	int	10	number of records
startIndex	False	int	0	starting record index
startDate	False	str or datetime		the start date
endDate	False	str or datetime		the end date

3.1 Examples

search=Search(a)
mongo_search=search.getProducts('{{ID:DATASET}}',maxRecords=1,startIndex=0)

4 - getData

This module provides data access of raster, spatial subset and timeseries.

Class contructor and parameters

from adamapi import GetData
data=GetData(a)

Parameters:

position/keyword	mandatory	type	default	description
0	True	Auth Instance		The ADAMAPI authorized instance obtained in the section 1-Auth

Public methods and parameters

• .getData() --> To retrieve a product
  

Parameters to retrive a product:

position/keyword	mandatory	type	default	description
0	True	str		The datasetId
1	True	str		The productId
outputFname	False	str	"adamapiresults/datasetId"	absolute filename or relative filename without extension. If not set, the retrived product is saved in "adamapiresults/datasetId.tif"

Parameters to retrive a subset or a timeseries:

position/keyword	mandatory	type	default	description
0	True	str		The datasetId
1	True	str		startDate
2	True	str		endDate
3	False	boolean	False	asyncronous management for subset and timeseries order
geometry	True	str or geojson		GeoJson geometry, if the geometry is a Point the api return a timeseries
outputFname	False	str	"adamapiresults/datasetId"	absolute filename without extension. If not set, the retrived product is saved in "adamapiresults/datasetId"

4.1 Examples

data=GetData(a)
#to retrive a raster
image=data.getData('{{ID:DATASET}}',productId='{{productId}}')
#or image=data.getData('{{ID:DATASET}}',productId='{{productId}}',outputFname="adamapi/test_get_data")

#to retrive a subset
image=data.getData(datasetId, startDate, endDate, geometry = '{"type": "Polygon", "coordinates": [ [ [ 43.916666667, 15.716666667 ], [43.916666667, 15.416666667 ], [ 44.216666667, 15.416666667 ],     [ 44.216666667, 15.716666667 ],     [ 43.916666667, 15.716666667 ]]]}')
#to retrive a timeseries
px_series=data.getData(datasetId, startDate, endDate, geometry = '{"type": "Point","coordinates":[43.916666667, 15.716666667]}')

#asyncronous management
image=data.getData(datasetId, startDate, endDate, asyncron= True,geometry = '{"type": "Polygon", "coordinates": [ [ [ 43.916666667, 15.716666667 ], [43.916666667, 15.416666667 ], [ 44.216666667, 15.416666667 ],     [ 44.216666667, 15.716666667 ],     [ 43.916666667, 15.716666667 ]]]}')

#check order status
image=data.getData(datasetId, pk={{orderID}})