Metadata-Version: 2.1
Name: adamapi
Version: 1.0.1
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
Description: # 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
        
        ```bash
        sudo apt-get install python3-venv python3-gdal gdal-bin
        ```
        
        ## Install with pip
        ```bash
        VENVNAME="adamapi"
        python3 -m venv "${VENVNAME}"
        source "${VENVNAME}/bin/activate";
        python3 -m pip install --upgrade pip;
        pip install adamapi==1.0.1
        ln -s "/usr/lib/python3/dist-packages/osgeo" "${VENVNAME}/lib/python3.7/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 data ( png, tiff, chart, gif, ... )
        
        ## 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. |
        
        ### 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}}' ) )
        ```
        
        ## 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. |
        | geometry | False | geojson | | search polygon in [geojson format](https://tools.ietf.org/html/rfc7946) |
        | outputAttributes | False | array of str | | list of attributes desired on the output dictionary. If not set all the attributes will be returned |
        | itemPerPage | False | int | 10 | number of records |
        | Index | False | int | 0 | starting record index |
        | startDate | False | str or [datetime](https://docs.python.org/3/library/datetime.html) | | the start date |
        | completationDate | False | str or [datetime](https://docs.python.org/3/library/datetime.html) | | the end date |
        | tile | False | str | | the tile identifier (MGRS for the sentinel, path and row for landsat, ... ) |
        
        ### 3.1 Examples
        ```python
        search=Search(a)
        mongo_search=search.getProducts('{{ID:DATASET}}',geometry={"type":"Polygon","coordinates":[[[-60,-45],[60,-45],[60,45],[-60,45],[-60,-45]]]},itemPerPage=1,Index=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**
        ```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)<br>
        Parameters:
        
        | position/keyword | mandatory | type | default | description |
        | ------ | ------ | ------ | ------ | ------ |
        | 0 | True | str |  | The datasetId |
        | timeStart | True | str or [datetime](https://docs.python.org/3/library/datetime.html) |  | the start date |
        | timeEnd | False | str or [datetime](https://docs.python.org/3/library/datetime.html) | timeStart | the end date |
        | geometry | False | geojson | | subset bbox in [geojson format](https://tools.ietf.org/html/rfc7946) |
        | tile | False | str |  | 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 |
        
        *  **.getChart()** --> to retrive a timeseries on a point in two different format(json or png)<br>
        Parameters:
        
        | position/keyword | mandatory | type | default | description |
        | ------ | ------ | ------ | ------ | ------ |
        | 0 | True | str |  | The datasetId |
        | timeStart | True | str or [datetime](https://docs.python.org/3/library/datetime.html) |  | the start date |
        | timeEnd | False | str or [datetime](https://docs.python.org/3/library/datetime.html) | 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  |
        
        
        ### 4.1 Examples
        ```python
        data=GetData(a)
        image=data.getData('{{ID:DATASET}}',timeStart= '{{datetime}}',timeEnd='{{datetime}}',tile="{{MGRS_TILE OR PATHROW}}",outputFormat='tif',outputFname="",scale=0.1)
        ```
        ```python
        data=GetData(a)
        image=data.getChart('{{ID:DATASET}}',timeStart='{{datetime}}',timeEnd='{{datetime}}',latitude=42.7998,longitude=19.5481,outputFname="chart_example",outputFormat='json')
        ```
        
        # 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](https://tools.ietf.org/html/rfc7946)<br>
        In particular Polygons and MultiPolygons should follow the right-hand rule<br>
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Unix
Requires-Python: >=3.6
Description-Content-Type: text/markdown
