Arlula Satellite Imagery API: Beginners Guide

Introduction

In this tutorial we’ll be showing you how to get started with Arlula and order your first Landsat 8 satellite imagery datasets for free using our API.

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!

Step 1: Signup

If you’re new to Arlula, you’ll need to create an account, this is a fairly simple process that should only take a few minutes.

Visit https://api.arlula.com/signup and create an account.

Once you signup you’ll receive an email from us, if you cannot find it make sure to check your spam folder!

Step 2: Generate your API credentials

Once you’ve created your account and logged into the Arlula platform you’ll need to create generate new API credentials so you can interact with our infrastructure. If you’re logging in for the first time, you’ll be prompted to generate your first API credentials, where a new window will pop up.

The three main fields that you’ll need to fill out in order to generate new API credentials are API Name, API Support Email and API Security Key. Your 30 character long API security key is different to your Arlula account password and will be used to securely send encrypted API requests over the web.

DO NOT FORGET YOUR API SECRET! A good idea is to save it offline somewhere safely as you’ll need this later.

Once you’ve created your credentials a new page will open to the Arlula API documentation page. If you need to check your API key, or update your secret you can always do this by heading to the details section of your API credentials.

Step 3: Postman Install

Now that we’ve created our Arlula accounts and API credentials we can start making requests to the API. A great 3rd party tool that we use at Arlula for testing and evaluating APIs is called Postman. We’ll be using Postman today in order to make our first requests.

Start by visiting https://www.postman.com/downloads/ and downloading the software to your computer. Once the software is installed and opened, you’ll see something similar to this.

Step 4: 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, which requests download of a resource associated with an order, such as the imagery or its metadata

Begin by clicking on the “Collections” tab and create a new collection. Feel free to give it whatever name you like.

Next, we’re going to use the Search endpoint in order to find the latest imagery over Sydney, Australia. Click the “+ New” button in the top left corner of the Postman screen and select “Request”. Give it the name “Get” and then press the Save button (making sure it’s saved to the Collection we just made).

Click on the “Authorization” button and select “Basic Auth” from the drop down menu. Once you’ve selected these features, you’re now able to enter your API key for the “Username” field, and your API Secret for the “Password” field.

Now that we’ve entered the authorization details we’ll be able to conduct a search request. You can conduct a search with the Arlula API based on 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. Copy the below endpoint into the address bar at the top of the tab.

https://api.arlula.com/api/search?start=2019-01-03&end=2019-04-13&res=low&lat=-33.8523&long=151.2108

Once you’ve copied in the above HIT SEND!

Congratulations, you’ve just searched through millions of available satellite images in archives around the world.

Step 5: 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. These results will be returned to you in JSON format.

Each result contains many different parameters (“supplier”, “eula”, “id” etc, etc) that will help you to compare different imagery scenes against each other. For more information on all of the different types of parameters you can view this at www.arlula.com/documentation/ under our search API endpoint details.

If you’d like to save a copy of your results through Postman you can press the “Save Response” button in order to keep a copy.

Step 6: 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 you finish activating your account which will allow you to make imagery purchases.

In order to place an order we’ll have to use the “new order” endpoint and send a Post request using Postman. Create a new “Request” under your Collection like before, using “order” as the name for the new request. Once saved, click the “GET” prefix before the URL field and select “Post” from the dropdown menu.

You’ll also need to change your authorization details to “Basic Auth” as we did in Step 4. Once we’ve changed to the correct authorization we can now place a new order. To do this copy the following link into the address bar.

https://api.arlula.com/api/order/new

This endpoint will allows us to send specific information to the Arlula API. Once you’ve entered the above URL, press the “Body” button underneath the address bar and click the “raw” radio button. Select JSON from the drop down menu to the right that appears once you’ve selected raw.

Now you’re ready to send a new order request.

We’re now going to go back to the Get tab that we used to conduct our first API search and find the results section. In the results section we’re going to copy the “eula” and “id” parameters from the first search result (highlighted below).

You’ll have to go back into your search query and find a suitable eula and product id (any eula and id that correspond to a Landsat image should be fine for this step. Once you’ve found a Landsat image you want to order you’ll need to copy the id and the eula into the follow JSON query body.

{
"id": "",
"eula": "",
"seats": 1,
"trim": false,
"webhooks": [],
"emails": []
}

Your JSON query body should now look something like this.

{
"id":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJMQzA4X0wxVFBfMDg5MDg0XzIwMTkwMTIyXzIwMTkwMTIzXzAxX1JUIiwiaWF0IjoxNTk2NzY2NDc1LCJpc3MiOiJBcmx1bGEgQXJjaGl2ZSIsInR5cGUiOiJhcmNoaXZlIiwic3VwcGxpZXIiOiJsYW5kc2F0IiwiZXVsYSI6Imh0dHBzOi8vY3JlYXRpdmVjb21tb25zLm9yZy9saWNlbnNlcy9ieS8zLjAvbGVnYWxjb2RlIiwicHJpY2UiOnsic2NlbmUiOnsiYmFzZSI6MCwic2VhdHMiOm51bGx9fX0.vfI_-tchFcnsqBRWa_d_aZ6WM1nemtvX_VUfzWx6OUw",
"eula": "https://creativecommons.org/licenses/by/3.0/legalcode",
"seats": 1,
"trim": false,
"webhooks": [],
"emails": []
}

Once you’ve done this, you should get a result like this (as long as your JSON Query body is formatted correctly!)

Now that we’ve placed an order, for the specific satellite imagery scene we can choose what files we want to download.

Step 7: 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’ll need to use the “Get Resource” API endpoint. We need to create a new Get Request tab like we did previously, and name it “Get Resource”. Make sure you implement “Basic Auth” just as we did in previous steps.

In the Order results section, you can see how many different files are associated with a specific satellite imagery scene. Each individual file has its own specific id that you can use to place a download request for, so we’re going to be downloading the large thumbnail. To find the id associated with this file, we’ll scroll down through the results of the previous until we find a file type listed as “thumb”. There may be more than one file of this type, so because we want to find the large thumbnail we can look for the file name that mentions “thumb_large.jpg”. Simply copy the id associated with this file to use in the Get Resource search request.

The id you located will now be used to conduct an order request. Paste the id at the end of the below search link:

https://api.arlula.com/api/order/resource/get?id=

All you need to do is paste the complete link with the search id in the “Get Resource” address bar and Hit Send!

Congratulations! You’ve just completed your first satellite imagery order. If successful, the jpg thumbnail should be displayed in the body of your request. You can save this thumbnail by using the “save response” feature in Postman.

Now that you’ve made your first download, try downloading other files associated with this, or even making other orders!

Note that Postman isn’t designed to download large files, but have a go at trying different methods. Or use our Python Package.

https://pypi.org/project/arlulaapi/

If you have any questions or would like to learn more please feel free to contact the Arlula team at hello@arlula.com