Maxar ARD SDK¶
A Python SDK and CLI for working with ARD Imagery
max_ard consists of a Python SDK for selecting, ordering, and working with Maxar ARD imagery and a set of CLI tools for common tasks. These include:
- Authentication and access to the ARD API
- Running ARD Selects and working with their results
- Searching using the lower-level Metadata API
- Create and manage Monitors to alert when new imagery is available
- Generate and run ARD orders
- Explore and work with ARD products
The goal of the SDK is to provide high-level abstractions so users can get quickly get started with ARD. However, the SDK is not required to work with the ARD API or deliverables. It is possible to communicate with the HTTP API and order ARD just using the
requests package, as well as read pixels from ARD tiles just using
rasterio or any other Python package that can read TIFF files.
max_ard is tested on Python 3.7 - 3.9, due to the availability of Python wheels for all of the package's dependencies.
For general information about Maxar ARD, see the main documentation at https://ard.maxar.com/docs
max_ard comes in two flavors:
max_ardis the base version. This lets you interact with the API and explore ARD collections in S3 or copied to your local system. It lacks the requirements
Rasteriowhich you would use to read the ARD raster and vector products. This makes installation of
max-ardfaster and easier. You can install any of the two libraries later if needed.
max_ard[full]includes 'Fiona' and 'Rasterio' for users who want to read data from the raster and vector ARD files.
Functionality and requirements¶
|Read ARD vector masks
|Read spatial files for AOIs
|Output QGIS layers and shapefiles
OS X and Linux Installation¶
To install the base version:
pip install max_ard
For the full version:
pip install 'max_ard[full]'
Note that Python 3.10 does not have Rasterio wheels yet so the full installation will require manual build steps.
Earlier versions of
max_ard are available at
packages.ard.maxar.com. Starting at version 1.5.2 this package became available through PyPI.
We highly recommend Windows users use a Conda-based installer to manage their environment and dependencies. We recommend Miniforge but any of the "-Conda" or "-Forge" based installers will work.
max_ard requires Shapely and these installers will install it correctly. To install the base
max_ard package run:
% conda create -n ard-env shapely
% conda activate ard-env
% pip install max_ard
To install the full
max_ard version, you should also use Conda to install
Rasterio. Note this requires you to use Python 3.7 until Conda-Forge releases updated Rasterio packages. You do not need to specify
max_ard[full] when using Conda.
% conda create -n ard-env python=3.7 gdal rasterio fiona shapely
% conda activate ard-env
(ard-env) % pip install max_ard
If you install Fiona, you will likely need to set the PROJ database location. If you see warnings about "Cannot find proj.db", run this command in your ARD env:
(ard-env) % $Env:PROJ_LIB = "$Env:CONDA_PREFIX\Library\share\proj\proj.db"
If you do not use Anaconda or Miniconda, you can try to install pre-compiled binaries for the C-based dependencies in this order:
- First install the Microsoft C++ Tools
Next install the Wheel files for GDAL, Rasterio, and Fiona. From the links below, download the correct wheel file for your system. You will need to match Python versions (
-cp38- means Python 3.8 and so on) and system architecture (
most likely AMD64). Once you have downloaded the file, install it with
pip install path/to/package.whl.
--upgrade parameter in
pip install max_ard --upgrade
If you are using the SDK or CLI to access data in a private S3 bucket, you will need to configure your AWS credentials locally. We recommend installing the AWS CLI tools and following their configuration guide.
To interact with the ARD API services, you will need to obtain and configure ARD account credentials. Currently we store the credentials locally in a file in your home directory called
.ard-config. It should contain:
user_name = <your user name>
user_password = <your password>
The CLI tools can be used to create this file if it does not exist:
Autogenerated documentation of
max_ard and companion grid library
maxar_ard_grid can be found at:
Several sample datasets are available in the bucket
s3://maxar-ard-samples/v4. No authentication is required for access. To browse the sample data structure you can use this web-based file browser.