Start using your Arlula API key with Postman

Introduction

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

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!

What you’ll need:
Access to the Arlula API account login page.
Free API development application Postman. *any API application will work, but the steps below are for this specific application. 

Step 1: Postman Install

Now that we’ve created our Arlula account 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. If you haven’t already, visit https://www.postman.com/downloads/ to download this software to your computer. Once it’s installed and opened, you’ll see something similar to the screenshot below.

Step 2: Authentication

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.

    • Archive Search, for obtaining a list of satellite imagery available for the request’s search criteria
    • Archive Order, which creates a new order, and pays for purchasing imagery
    • Order History, which will list all past and current orders on your account
    • Order Details, which will list the order details and any associated resources of an order on your account
    • Resource Download, which requests download of a resource associated with an order, such as the imagery or its metadata

All of these endpoints require a set of API credentials with which to make the request (if you have not done so already, set up your API account by following this tutorial).

In order to share include these credentials in your request;

  1. Begin by loading Postman and clicking on the “Collections” tab to create a new collection. Feel free to give it whatever name you like.
  2. Click on the collection itself in your collections sidebar, and you’ll see something like the following
  3. Change the authorization type to “Basic Auth”
  4. Add you API Key as the “Username” and your API Secret as the “Password” (don’t forget to save once your done)

Step 3: Search Imagery Archives

Now we’re ready to start making API requests. As a first step, lets search for available imagery:

  1. 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” (or right click your collection and select “Add request”). Give it the name “Search” by clicking “New Request” in the heading and typing the name (if its not already selected), and then press the Save button (making sure it’s saved to the Collection we just made if you clicked “new”).

  1. Lets setup the request by adding the URL https://api.arlula.com/api/archive/search to the request URL section below the request name at the top of the window, this is the base path for all search requests, and from here we can specify our search criteria,
  2. By utilising search criteria you can find satellite imagery captured on different dates at different resolutions and in different locations all over the world. Any search with the Arlula API has 2 mandatory criteria:
    • Time: Start date (and an optional end date) (YYYY-MM-DD).
    • Location: a point or region of the surface of the earth defined by a bounding box.
  3. 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, for a full list of the filter criteria, see the search request section of our API documentation.
  4. We’ll be using an endpoint to search for low resolution imagery over Sydney between 3/1/2019 and 13/4/2019.
    You could either copy the below URL into the address bar at the top of the tab, or enter the attributes in the “Params” pane individually.
    https://api.arlula.com/api/archive/search?start=2019-01-03&end=2019-04-13&res=low&lat=-33.8523&long=151.2108
  5. Once you’ve copied in the above hit the SEND button beside the url. Congratulations, you’ve just searched through millions of available satellite images in archives around the world.

Step 4: 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 (such as “supplier”, “bands”, “offNadir”, 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 results details section.

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 5: 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 for commercial use.

  1. In order to place an order we’ll have to use the “archive order” endpoint and send a POST request using Postman. Create a new “Request” under your Collection like before, naming it “order” this time. Once saved, click the “GET” prefix before the URL field and select “POST” from the dropdown menu.
  1. Now add the order endpoint URL to the address bar:
    https://api.arlula.com/api/archive/order
  2. 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 and select JSON from the format drop down menu to the right that appears once you’ve selected raw.
  1. Now you’re ready to send a new order request. We’re now going to go back to the Search tab that we used to conduct our first API search and find the results section. In the results section we’re going to find a free landsat 8 result and copy the “orderingID” parameter (highlighted below), along with the bundle “key” and license “href”, as we will need these to order.
  1. The “orderingID”, bundle “key” and license “href” parameters are the three critical parameters that will allow you to place an order through the API. After copying these parameters from the desired landsat image in the previous step, we’re going to include them in a JSON query shown below to make out order request. *full descriptions of ordering parameters (including those not included or described here) are available in our documentation but in summary;
    the ordering ID uniquely identifies the scene we want to order,
    the bundle key identifies which version of the scene we want to order the scene (only one option for landat), and
    the license URL (href) identifies the licensing we acknowledge and accept by placing the order (creative commons 3.0 for landsat).
  1. Your final JSON query body should now look similar to the example below.

Once you’ve done this, hit SEND to place the request and you should get a result like in the screenshot below (assuming no errors and your JSON was correctly formatted)

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

Step 6: 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) containing the imagery at full resolution and can range from hundreds of megabytes to tens of  gigabytes in size.

  1. We’ll download the large thumbnail file from this Landsat scene. In order to do this, we’ll need to use the “Resource Download” API endpoint. To do this, create a new Request tab like we did previously, and name it “Download Resource” for the new GET request.
  2. In the Order results section of the last request, you can see the 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, we’re going to be downloading the thumbnail. To find the id associated with this file, we’ll scroll down through the results of the previous until we find a resource with the roles [“metadata”, “raster”, “summary”, “thumbnail”] (or with type “thumb” or format “image/jpeg”). Simply copy the id associated with this file to use in the Get Resource search request.
  3. The id you located will now be used to conduct an order request. Paste the id at the end of the following URL:
    https://api.arlula.com/api/order/resource/get?id=
  4. This final link should look something like this: https://api.arlula.com/api/order/resource/get?id=cbf28cc1-4730-446c-a600-de9c52f1588b
  5. All you need to do is paste the complete link with the search id in the “Download Resource” address bar and click Send.
  1. Congratulations! You’ve just completed your first satellite imagery order and downloaded some of its data.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.
  2. Now that you’ve made your first download, try downloading other files associated with this order, such as its metadata, or even making other orders!

Note that Postman isn’t designed to download large files, but have a go at trying different methods. Alternatively you can use our Python Package available here: https://pypi.org/project/arlulacore/

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