Start using your Arlula API key with Postman
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!
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: 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 loading Postman and clicking on the “Collections” tab to 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. 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. Copy the below endpoint into the address bar at the top of the tab.
- 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 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. These results will be returned to you in JSON format.
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.
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 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.
- 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:
- 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).
- The “eula” and “id” parameters are two important 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 paste them into the JSON query format shown below. *full descriptions of parameters are available in our documentation.
- Your final JSON query body should now look similar to the example below.
Once you’ve done this, you should get a result like in the screenshot below (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 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’ll need to use the “Get Resource” API endpoint. To do this, 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:
- This final link should look something like this: https://api.arlula.com/api/order/resource/get?id=cbf28cc1-4730-446c-a600-de9c52f1588b
- 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. Alternatively you can use our Python Package available here: https://pypi.org/project/arlulaapi/
If you have any questions about this specific tutorial or would like to learn more please feel free to contact the Arlula team at firstname.lastname@example.org.