adamapi 2.0.1

Python Adam API

Installation

Versioning

1. adamapi==1.0.1 , This package works only with ADAMCORE 1.
2. adamapi==2.0.1 , This pachage works only with ADAMCORE 2. (ADAMCORE 2 in development phase)

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.1
ln -s "/usr/lib/python3/dist-packages/osgeo" "${VENVNAME}/lib/${PYTHONVERSION}/site-packages/osgeo"

API DEFINITIONS

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

1. Auth --> the authorization module
2. Datasets --> to retrieve available datasets
3. Search --> to get image lists, polygons, tiles and other metadata
4. GetData --> to retrieve data ( png, tiff, chart, gif, ... )

1 - Auth

This module takes care of user authentication.
Without instancing an object of this module other components will not works.
Authentication is based on the ADAMAPI_KEY, a key that uniquelly identify a user in the ADAM-CORE endpoint.

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://explorer.adamplatform.eu

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

position/keyword	mandatory	type	default	description

1.1 - ADAMAPI_KEY retrieval

To get the ADAMAPI_KEY access the refence ADAM portal and:

1. Select the "user icon" on the top right
2. Click on the "USERNAME" and open the "User Management" popup
3. Click on the "Api Key" to display your key

*Command-line ADAMAPI_KEY retrieval TBP*

1.2 - ADAMAPI_KEY setup

There are three method 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('bdjmgBl02muSHSG0a4XhyZBjXXQ')
a.setAdamCore('https://explorer.adamplatform.eu')

2. Export two envars like

#open a Terminal and type:
export ADAMAPI_KEY='bdjmgBl02muSHSG0a4XhyZBjXXQ'
export ADAMAPI_URL='https://explorer.adamplatform.eu'

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

key=bdjmgBl02muSHSG0a4XhyZBjXXQ
url=https://explorer.adamplatform.eu

1.3 - Examples

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

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

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 information 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.
geometry	False	geojson		search polygon in geojson format
outputAttributes	False	array of str		list of attributes desired on the output dictionary. If not set all the attributes will be returned
maxRecords	False	int	10	number of records
startIndex	False	int	0	starting record index
startDate	False	str or datetime		the start date
completationDate	False	str or datetime		the end date
tile	False	str		the tile identifier (MGRS for the sentinel, path and row for landsat, ... )

3.1 Examples

search=Search(a)
mongo_search=search.getProducts('{{ID:DATASET}}',geometry={"type":"Polygon","coordinates":[[[-60,-45],[60,-45],[60,45],[-60,45],[-60,-45]]]},maxRecords=1,startIndex=0)

4 - getData

This module provides data access of raster and timeseries of products, up to pixel granularity, including the support of different image encodings, sequence of images in three different format or direct link to download the image or the images(json, tif, png, gif, png_preview ).

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 rasters in different encodings (tif, png, gif, png_preview)
  

Parameters:

position/keyword	mandatory	type	default	description
0	True	str		The datasetId
timeStart	True	str or datetime		the start date
timeEnd	False	str or datetime	timeStart	the end date
geometry	False	geojson		subset bbox in geojson format
tile	False	str	{{mgrstile}} or {{pathrow}}	the tile identifier (MGRS for the sentinel, path and row for landsat, ... )
outputFormat	False	str	tif	output file format [ 'tif', 'gif', 'png', 'png_preview' ]
outputFname	False	str	{{datasetId}}	output fillename pattern. If not specified the url is returned
scale	False	double		Raster rescale factor
filter	False	bool	True	NoData value filter

• .getChart() --> to retrive a timeseries on a point in two different format(json or csv)
  

Parameters:

position/keyword	mandatory	type	default	description
0	True	str		The datasetId
timeStart	True	str or datetime		the start date
timeEnd	False	str or datetime	timeStart	the end date
latitude	False	double		latitude coordinate
longitude	False	double		longitude coordinate
outputFormat	False	str	json	output file extension
outputFname	False	str	{{datasetId}}	output fillename pattern
tile	False	str	{{mgrstile}} or {{pathrow}}	the tile identifier (MGRS for the sentinel, path and row for landsat, ...

4.1 Examples

data=GetData(a)
image=data.getData('{{ID:DATASET}}',timeStart= '{{datetime}}',timeEnd='{{datetime}}',tile="{{MGRS_TILE OR PATHROW}}",outputFormat='tif',outputFname="",scale=0.1)

data=GetData(a)
image=data.getChart('{{ID:DATASET}}',timeStart='{{datetime}}',timeEnd='{{datetime}}',latitude=42.7998,longitude=19.5481,outputFname="chart_example",outputFormat='csv')

Appendix 1 - Data format

date and date+time

Supported string date/date+time format are:

• '%Y.%m.%d %H:%M:%S',
• '%Y%m%d %H:%M:%S',
• '%Y-%m-%dT%H:%M:%S',
• '%Y-%m-%dT%H:%M:%S.%f',
• '%Y-%m-%dT%H:%M:%SZ',
• '%Y-%m-%dT%H:%M:%S.%fZ',
• '%Y-%m-%d %H:%M:%S',
• '%Y.%m.%d',
• '%Y%m%d',
• '%Y-%m-%d'

GeoJson

Geometry have to follow the latest geojson standard rfc7946
In particular Polygons and MultiPolygons should follow the right-hand rule