Metadata-Version: 2.1
Name: adamapi
Version: 2.0.1rc1
Summary: Python Adam API
Home-page: https://git.services.meeo.it/das/adamapi
Author: MEEO s.r.l.
Author-email: info@meeo.it
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Unix
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: imageio
Requires-Dist: requests (>=2.22.0)

# Installation

### Versioning

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

## Requirements

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

## Install with pip
```bash
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.<br>
A more complete and interactive documentation are provided through a predefined jupyter notebook *(LINK to notebook TBP)*.<br>
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 tiff data

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

**Class contructor and parameters**
```python
from adamapi import Auth
a = Auth()
```
Parameters:<br>

| position/keyword | mandatory | type | default | description |
| ------ | ------ | ------ | ------ | ------ |
| | | | | |

**Public methods and parameters**

*  **.setKey()** --> To setup the ADAMAPI_KEY<br>
Parameters:

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

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

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

*  **.authorize()** --> to instanciate an auth object<br>
Parameters:

| position/keyword | mandatory | type | default | description |
| ------ | ------ | ------ | ------ | ------ |
| | | | | |


### 1.1 - ADAMAPI_KEY retrieval
To get the ADAMAPI_KEY access the refence ADAM portal and:<br>
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
<br>
*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()
```python
from adamapi import Auth
a = Auth()
a.setKey('bdjmgBl02muSHSG0a4XhyZBjXXQ')
a.setAdamCore('https://explorer.adamplatform.eu')
```
2. Export two envars like
```bash
#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
```text
key=bdjmgBl02muSHSG0a4XhyZBjXXQ
url=https://explorer.adamplatform.eu
```
### 1.3 - Examples
After ADAMAPI_KEY has been setted up, an auth instance can be created with:
```python
from adamapi import Auth
a = Auth()
a.authorize()
```

## 2 - Datasets
This module provides datasets discovery functionality.

**Class contructor and parameters**
```python
from adamapi import Datasets
datasets = Datasets( a )
```
Parameters:<br>

| 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<br>
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:
```python
datasets = Datasets(a)
print(datasets.getDatasets())
```
2.  To get detailed information about a specific dataset
```python
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**
```python
from adamapi import Search
search = Search( a )
```
Parameters:<br>

| 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<br>

Parameters:

| position/keyword | mandatory | type | default | description |
| ------ | ------ | ------ | ------ | ------ |
| 0 | True | str | | The datasetId. |
| 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](https://docs.python.org/3/library/datetime.html) | | the start date |
| completionDate | False | str or [datetime](https://docs.python.org/3/library/datetime.html) | | the end date |


### 3.1 Examples
```python
search=Search(a)
mongo_search=search.getProducts('{{ID:DATASET}}',maxRecords=1,startIndex=0,outputAttributes=['productId'])
```

## 4 - getData
This module provides data access of raster .

**Class contructor and parameters**
```python
from adamapi import GetData
data=GetData(a)
```
Parameters:<br>

| 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)<br>

Parameters:

| position/keyword | mandatory | type | default | description |
| ------ | ------ | ------ | ------ | ------ |
| 0 | True | str |  | The datasetId |
| 1 | True | str |  | The productId |
| outputFname | False | str | {{productId}} | output filename pattern. if not set, the product id is the filename |


### 4.1 Examples
```python
data=GetData(a)
image=data.getData('{{ID:DATASET}}','{{productId}}')
#or
image=data.getData('{{ID:DATASET}}','{{productId}}',outputFname="adamapi/test_get_data")

```


