Skip to main content

Python Adam API

Project description

Installation

Versioning

  1. adamapi==1.0.1 , This package works only with ADAMCORE 1.
  2. adamapi==2.0.10, 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')
  1. Export two envars like
#open a Terminal and type:
export ADAMAPI_KEY='<ADAMAPI_KEY>'
export ADAMAPI_URL='https://test.adamplatform.eu'
  1. 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.

This .getDatasets() function can be used to retrive additional filters which are described in the key filtersEnabled (if exists).

2.1 Examples

This module can be used in 2 different ways.

  1. To list all available datasets:
datasets = Datasets(a)
print(datasets.getDatasets())
  1. To get detailed metadata about a specific dataset
datasets = Datasets(a)
print( datasets.getDatasets( '{{ID:DATASET}}' , page=0 , maxRecords=10 ) )
  1. To get filtersEnabled. To use this additional filters see first example in Search section.
datasets = Datasets(a)
out=datasets.getDatasets("{{ID:DATASET}}")
print(out["filtersEnabled"])

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

  1. Example1:
search=Search(a)
mongo_search=search.getProducts('{{ID:DATASET}}',maxRecords=1,startIndex=0,platform="{{VALUE}}")
  1. Example2:
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
- get order info:
image.pk -> order key

image.status -> order status

image.location -> order location when status is completed

image=data.getData(datasetId, asyncron= True,pk=image.pk)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for adamapi, version 2.0.10
Filename, size File type Python version Upload date Hashes
Filename, size adamapi-2.0.10-py3-none-any.whl (13.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size adamapi-2.0.10.tar.gz (11.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page