Travel the world with the Arlula #api and #python

Start using your Arlula API key with Python 1

Introduction:
In this tutorial we’ll be showing you how to order your first Landsat 8 satellite imagery for free using our API and Python.
The Arlula API allows users to query databases of satellite imagery from vendors around the world. This powerful tool allows users to search and compare the quality of global image datasets and order them at scale. The Arlula API is a new way in which people from around the world can access timely satellite imagery and create their own data streams from space!
The Arlula archive Python package makes it easy to access all of the API functionality without having to do any of the hard work!
What you’ll need:
Access to the Arlula API account
Open source

Step 1: Python Package Install

In a terminal/command prompt, paste the following command:
pip install arlulaapi

NOTE common problem: if you get an error along the lines of ‘pip could not be found‘ or ‘pip could not be recognised‘, you might need to Python to your PATH.

Step 2: Search Imagery Archives

Now we’re ready to start making API requests. The Arlula API has a variety of GET and POST requests that can be made to perform different tasks.

Search, for obtaining a list of satellite imagery available for the request’s search criteria

Orders, for requesting purchase of imagery and its associated data that will be delivered to the provided contact. This is broken down into:

• New order, which creates a new order, and pays for purchasing imagery
• List orders, which will list all past and current orders on your account.
• Get order, which will list the details and any associated resources of an order on your account
• Get resource](https://www.arlula.com/documentation/#get-resource), which requests download of a resource associated with an order, such as the imagery or its metadata.

Begin by creating a new Python file – let’s call it sample.py
First, we want to import the arlulaapi package and add our credentials:

import arlulaapi

arlula_session = arlulaapi.ArlulaSession(yourkey, yoursecret)

This creates an Arlula Session that will automatically authenticate all API calls with your credentials.

Now that we’ve entered the authorization details we’ll be able to conduct a search request. By utilising search criteria you can find satellite imagery captured on different dates at different resolutions and in different locations all over the world. You can conduct a search with the Arlula API based on the following 3 different search criteria.

-Time: Start and end dates (YYYY-MM-DD).
-Image Resolution: vhigh(<0.5m), high(0.5m-1m), med(1m-5m), low(5m-20m), vlow(>20m).
-Location: Point search or bounding box.

By utilising this search criteria you can find satellite imagery captured on different dates at different resolutions and in different locations all over the world.

We’ll be using an endpoint to search for low resolution imagery over Sydney between 3/1/2019 and 13/4/2019:

import arlulaapi

arlula_session = arlulaapi.ArlulaSession(yourkey, yoursecret)
search_result = arlula_session.search(
    start="2019-01-03",
    end="2019-04-13",
    res="low",
    lat=-33.8523,
    long=151.2108
)
print(search_result[0].thumbnail)

Step 3: Results

Now that you’ve conducted your first search with the Arlula API, you’ll be greeted with your search results. For any given search you could receive hundreds of results which represent individual imagery scenes captured from different satellites.

The results are returned as a list of Python objects. For instance, you can print out the thumbnail of the first result using print(search_results[0].thumbnail).

Each result contains many different parameters (such as “supplier”, “eula”, “id”, etc) that will help you to compare different imagery scenes against each other. You can learn more about these parameters on our documentation page under our search API endpoint details.

Step 4: Order satellite imagery

Now that we’ve conducted a basic search using the Arlula API. We’re ready to place an order for some satellite imagery. We’ll be ordering freely available Landsat imagery, but you can also order commercial high resolution imagery from other satellite imagery operators through our API once your account is activated.

Now you’re ready to send a new order request. From the search results, we need to choose imagery to order, and copy its eula and id. To do so, let’s choose the first landsat image with cloud<5.(Code below)

Now that we have that info, we can use the arlulaapi order method. The following code selects the desired imagery and orders it, before printing the details of the order.

for result in search_result:
    if result.supplier=='landsat' and result.cloud < 5:
        eula=result.eula
        id=result.id
        break

order = arlula_session.order(
    id=id,
    eula=eula,
    seats=1,
    trim=False,
    webhooks=[],
    emails=[]
)
print(order)

Step 5: Download your order

Now that we’ve placed an order you’ll receive a list of all the different files associated with that imagery scene. There are several different files associated with each scene, ranging from meta data files all the way to raw imagery files (tiff files) that are super high resolution and can be hundreds of megabytes in size.

We’ll download the large thumbnail file from this Landsat scene. In order to do this, we need the id from the order above. (If you lose this, you can always look at your orders with the list_orders functionality). The order also contained a list of resources, we need to pick a resource from there to download. Let’s download the first large jpg we come across.

The below code gets the above data and then uses the get_resource method.

for resource in order.resources:
    if resource.name.endswith("large.jpg"):
        resourceid = resource.id
        break

arlula_session.get_resource(
    id=resourceid,
    filepath='demo.jpg'
)

The code will output a loading bar:

[██████████████████████████████████████████████████]100.00%
download complete
and save the file to the desired location.

The Python package is also able to download all resources associated with an order and download to the specified folder, given the orderid:

orderid = order.id

arlula_session.get_order_resources(
    id=orderid,
    folder='demo'
)

Step 6: Putting it all together

Putting it all together:

import arlulaapi

arlula_session = arlulaapi.ArlulaSession(yourkey, yoursecret)
search_result = arlula_session.search(
    start="2019-01-03",
    end="2019-04-13",
    res="low",
    lat=-33.8523,
    long=151.2108
)

for result in search_result:
    if result.supplier=='landsat' and result.cloud < 5:
        eula=result.eula
        id=result.id
        break

order = arlula_session.order(
    id=id,
    eula=eula,
    seats=1,
    trim=False,
    webhooks=[],
    emails=[]
)

for resource in order.resources:
    if resource.name.endswith("large.jpg"):
        resourceid = resource.id
        break

arlula_session.get_resource(
    id=resourceid,
    filepath='demo.jpg'
)

orderid = order.id

arlula_session.get_order_resources(
    id=orderid,
    folder='demo'
)

If you have any questions about this specific tutorial or would like to learn more please feel free to contact the Arlula team at [e-mail].