Package: vds-api-client
(Command line) interface to download data batches directly from the VanderSat APIDescriptionInstallation instructionsUsing this module, one can get data from the VanderSat API using either:Command Line Interface (CLI)Python APICompatible for Linux, Mac and WindowsPython >= 3.6This package offers an easy interface to the asynchronous endpoints offered by
theVanderSat API. However, not all available
endpoints can be accessed through this package.InstallationRequired packagesclickrequestspandasclick_datetimejoblibSetting up an environmentIf you don’t have an environment yet or would like a new one, use the following line to make a new one usingconda$ conda create-nvds_api-cconda-forgepython=3 requests"click>=7"pandas joblib pipactivate it$ conda activate vds_apiand follow the installation stepsInstalling the clientThe package can be installed directly from PyPI. Activate your environment and then install with$ pip installvds-api-clientWith this activated environment one can access the vds cli with$vds-api(If not, your installation did not succeed)Command line interfaceAvailable CLI commands$vds-apiwill show all available commands which should include:grid- download gridded datainfo- Show info for this accounttest- test connection, credentials and if api is operationalts- download time-series as csv over points or roisCalling any of these commands should be done after suppliying credentials:$ vds api-u[username]-p[password] [command]And it is always a good idea to start with a test:$vds-api-u[username]-p[password] testCredentialsUsername / passwordFor each api call using the cli, the credentials need to be supplied.
These can be parsed along with the call by typing them explicitly like:$vds-api-u[username]-p[password] [command]However, it is also convenient to store the credentials so they don’t have to be
typed each time.Set the environment variables$VDS_USERand$VDS_PASSwith the correct values to automatically fill in your credentials.Planet internal SSOTo use Planet SSO get a token using the following procedureInstall:pip install planet-auth-utilsLogin:Default login: opens browser for authorization and listens locally for callback.plauth oauth loginGet Token:plauth oauth print-access-tokenFor each api call using the cli, the credentials need to be supplied.
These can be parsed along with the call by typing them explicitly like:$vds-api-t$(plauth oauthprint-access-token)[command]However, it is also convenient to store the credentials so they don’t have to be
typed each time.Set the environment variable$PL_VDS_OAUTH_TOKENwith the correct value to automatically fill in your credentials.This can be done in one step using this command:exportPL_VDS_OAUTH_TOKEN=$(plauthoauthprint-access-token)NoteThe Token will expire every 3600 seconds. If that happens during a
session logging in again and re-setting the environment variable will fix it.NoteWith the envvars set, the credentials don’t have to be parsed explicitly anymore thus the syntax reduces to:$vds-api[command]ImpersonationIf a user manages another VanderSat API user account, it can impersonate this user.
Through the CLI this can also be done using the--impersonateflag. e.g.$vds-api-umanager@company.com-ppassword--impersonate"user@company.com" [command]or when credentials were stored already$vds-api--impersonate"user@company.com" [command]Command specific optionsUse the help function to retrieve all options for the command line interface.$vds-api[command]--helpExample usage CLI V2 gridGet L-band for one month over NL in geotiff with 8 threads$vds-apigrid-pSM-SMAP-LN-DESC_V003_100-dr2015-04-012015-04-30-lo3 8-la50 54-oSM_L_Data-n8-vGet L+C+X-band for two dates over NL in netcdf$vds-apigrid-pSM-SMAP-LN-DESC_V003_100-pSM-AMSR2-C1N-DESC_V003_100-pSM-AMSR2-XN_V003_100-fnetcdf4-dr2016-07-012016-07-02-lo3.0 8.0-la50.0 54.0-oNCData-vExample usage CLI V2 tsGet L-band time-series for a region-of-interest (roi) and a lat-lon pair$vds-apits-pSM-SMAP-LN-DESC_V003_100-dr2015-05-012020-01-01-ll52 4.5-r3249-otsfold-vGet time-series with all additional columns$vds-apits-pSM-SMAP-LN-DESC_V003_100-dr2015-04-012019-01-01-ll52 4.5-otsfold--masked--av_win35--backward--clim-t20-cov-vExample usage Python APIAsynchronous requests can easily be downloaded using theVdsApiV2class.
For downloading of the desired files, the following steps need to be taken:API v2For the version 2 api, three steps have to be taken to download data from the api which are all methods of theVdsApiV2class:Generate a requestConfigure gridded data download or time-series download
through one ofgen_time_series_requests()orgen_gridded_data_request()Submit requestAfter generating all desired URIs, submit these withsubmit_async_requests()to start the processing of these jobsDownload filesGet all data usingdownload_async_files()Initialize classfromvds_api_clientimportVdsApiV2# Choose one of the following options to initializevds=VdsApiV2('username','password')vds=VdsApiV2()# extract login from $VDS_USER and $VDS_PASSImpersonate userWhen a user manages another account, it can impersonate this managed acount
which means that all requests will be done as if the impersonated user has made themvds=VdsApiV2('manager@company.com','password')# Start impersonationvds.impersonate('user@company.com')# do_requests# End impersonationvds.forget()Gridded data example [asynchronous]Request raster data using theproducts/<api_name>/gridded-dataendpointfromvds_api_clientimportVdsApiV2vds=VdsApiV2()vds.set_outfold('testdata/tiff')# Created if it does not existvds.gen_gridded_data_request(products=['SM-SMAP-LN-DESC_V003_100','SM-AMSR2-XN-DESC_V003_100'],start_date='2015-10-01',end_date='2016-09-30',lat_min=-3.15,lat_max=-1.5,lon_min=105,lon_max=107,nrequests=4)vds.submit_async_requests()vds.download_async_files()# Get information on the downloaded filesvds.summary()Time-series example [asynchronous]Request time-series data using theproducts/<api_name>/[point|roi]-time-seriesendpoints.fromvds_api_clientimportVdsApiV2vds=VdsApiV2()vds.set_outfold('testdata/csv')# Created if it does not existvds.gen_time_series_requests(products=['SM-XN_V001_100'],start_time='2018-01-01',end_time='2018-01-03',lons=[6.5],lats=[41.5],rois=[527,811])vds.submit_async_requests()vds.download_async_files()# Get information on the downloaded filesvds.summary()Notice that the lons and
lats are given in a list. When multiple points are defined, the latitude and longitude pairs can be added to the
single lists like this:lons=[6.5,7.5],lats=[41.5,45]and they will be processed in parallel.Re-download previous requestsRe-download data using previously generated uuids. Note that data is not stored indefinitely,
but within 7 days you should be able to re-download your data.fromvds_api_clientimportVdsApiV2vds=VdsApiV2()# Choose fromvds.uuids.append('5742540a-cf87-49dd-a6e7-d484de137324')vds.queue_uuids_files()# orvds.queue_uuids_files(uuids=['57f9950a-4e41-49dd-a6e7-d484de137324'])Get a single point valueExtract a single value based on a product-coordinate using theproducts/<api-name>/point-valueendpointfromvds_api_clientimportVdsApiV2vds=VdsApiV2()# Load using the roi-idval=vds.get_value('SM-XN_V001_100','2020-04-01',lon=20.6,lat=40.4)Load Roi time-series as pandas dataframe [synchronous]Request roi time-series data using theproducts/<api_name>/roi-time-series-syncendpoint
and load the result as a pandas.DataFramefromvds_api_clientimportVdsApiV2vds=VdsApiV2()# Load using the roi-iddf1=vds.get_roi_df('SM-XN_V001_100',2464,'2016-01-01','2018-12-31')# Load using the roi-namedf2=vds.get_roi_df('SM-XN_V001_100','MyArea','2016-01-01','2018-12-31')ROISKnowing and using the regions of interest (rois) attached to your account is now
easier using the client methods that allow you to filter the rois.fromvds_api_clientimportVdsApiV2vds=VdsApiV2()print(vds.rois)# ID / DISPLAY # |  # Name #  |   # Area #   |  # Created at #  |       # Description #
===============================================================================================
   25009  /  [X]  | Center     | 1.063e+05 ha | 2020-08-16 12:49 | Center pixels
   25010  /  [X]  | Right      | 9.949e+04 ha | 2020-08-16 12:58 | Right side pixels
   25011  /  [X]  | Bottom     | 6.616e+04 ha | 2020-08-16 12:59 | Bottom side pixels
   30596  /  [ ]  | NewName    | 9.140e+03 ha | 2020-09-18 07:19 | Same rectangleFiltersBut now, also filters can be applied to select Rois based on a criterium,
and give the corresponding ids:rois_filtered=vds.rois.filter(min_id=25000,max_id=25020,area_min=1e8,area_max=1e9,name_regex='Right|Bottom',description_regex='pixels',created_before=dt.datetime(2020,8,16,13,0),created_after=dt.datetime(2020,8,16,12,57),display=True)print(rois_filtered)print(rois_filtered.ids_to_list())# ID / DISPLAY # |  # Name #  |   # Area #   |  # Created at #  |       # Description #
===============================================================================================
   25010  /  [X]  | Right      | 9.949e+04 ha | 2020-08-16 12:58 | Right side pixels
   25011  /  [X]  | Bottom     | 6.616e+04 ha | 2020-08-16 12:59 | Bottom side pixels

[25010, 25011]GeometryAccessing the geometry is now supported through the geojson property:roi=vds.rois[25010]geojson=roi.geojson# Loads geometry from apiprint(geojson){'type':'MultiPolygon','coordinates':[[[[-5.237732,66.044796],[-5.237732,66.956952],[-5.018005,66.956952],[-5.018005,66.044796],[-5.237732,66.044796]]]]}UpdatingUpdating an Roi’s metadata is supported through the roi.update method:roi=vds.rois[30596]roi.update(name='New name',description='New description',display=False)print(vds.rois.filter(name_regex='New name'))# ID / DISPLAY # |  # Name #  |   # Area #   |  # Created at #  |       # Description #
===============================================================================================
   30596  /  [ ]  | New name   | 9.140e+03 ha | 2020-09-18 07:19 | New descriptionDeletingDeleting ROIS from your account is supported through thedelete_rois_from_account()method.
It expects a list of integers, or a filtered Rois instance. Now we can delete our Rois
quite easily like:vds.delete_rois_from_account(vds.rois.filter(description_regex='Selection to Delete'))