Theras A. Gordon Wood ‐ Data Science

Earth APIs: Ordering GeoTIFF Imagery

In this technical post we’ll be introducing and giving a brief demonstration to highlight the capabilities of our new Ordering APIs. If you haven’t yet signed up for the UrtheCast Platform yet, create an account now.

Ordering Satellite Imagery

Traditionally, ordering historical satellite imagery has been an arduous process. Time-consuming at best (and perhaps fruitless at worst), it has managed to remain an antiquated system involving phone calls, fax machines, customer service, and regular business hours.

Today, big data and analytics organizations want to ingest, analyze, and utilize new imagery as quickly as possible, every day. We’re excited to meet these challenges and believe our customers deserve tools and services that make their workflow simpler.

Our Solution: Earth APIs

One of the major innovations of the Internet era is the proliferations of APIs – or Application Programming Interfaces. If you’re not familiar with APIs, they can be thought of as “machine readable” interfaces that give you access to another service’s data and products. APIs enables two pieces of software to work together. To fulfill the needs of customers who are ingesting satellite imagery in GeoTIFF format, we’re excited to announce our new Ordering APIs.

Our Ordering APIs are designed to address the data-centric and analysis-driven demands of EO customers by making it easy to extract data from our archive, on-demand, from within existing software systems. Our entire archive of data, from every sensor, is now available for purchase through our Ordering APIs. New data is ingested and made available throughout the day, every day.

What this means is that locating and ordering data from UrtheCast is as simple as including a few statements of code within your existing software infrastructure. The time between needing historical imagery of an area of interest and having it available within your system for analysis is now reduced to a matter of minutes. This is a major milestone for us, and will enable our customers to extract the data they need, when they need it.

How it works

Our Ordering APIs are modeled after a traditional e-commerce workflow:

  1. Create a new Order (which you can think of as an empty shopping cart)
  2. Add Line Items to your Order – as many as you want. Each Line Item can be thought of as a product you’ve added to your shopping cart.
  3. Purchase your order. This triggers an authorization to your credit card on file and kicks off the processing jobs required to prepare your order. When your Order has been fully processed, your card will be charged.
  4. Download your delivered Line Items. Each Line Item will be made available via one or more unique, time sensitive, URLs.

The first product we’ve made available is a scene from our Archive. When ordering a scene, you may specify which spectral bands you wish to be included in your delivered product. In addition, you may crop the full scene down to include only your area of interest by including an Area of Interest ID or a GeoJSON polygon. Cropping a scene before delivery is more cost effective for the customer, and more efficient and performant to download.

In the future, we expect to release additional value added products that allow customers to more quickly derive business value from our data with increasing efficiency.

Earth API Demo

Here’s a quick demonstration of how you can use our Ordering APIs to programmatically acquire data. We will be utilizing an open source command line tool to simplify the ordering process.

Step 1: Find your scene

For this example, I’m interested in finding the most recent scene captured by our Theia sensor over Folsom Lake, located in California. I’m curious about the state of the California drought, and want to see how the lake looks.

To find the most recent scene, I’ll use our Archive API:

curl -X GET\?api_key\=$UC_API_KEY\&api_secret\=$UC_API_SECRET\&sort\=-acquired\&limit\=1\&sensor_platform\=theia\&geometry_intersects\=POINT\(-121.13388061523438+38.724090458956965\)\&cloud_coverage_lte\=20

Which gives me the following response:


As a quick summary, this API request is:

  • Querying our Archive API using my key and secret ($UC_API_KEY$UC_API_SECRET)
  • Sorting the response by the acquired key, which is when the image itself was acquired, in descending order
  • Limiting the response to only 1 scene – in this case, the most recently acquired
  • Restricting the response to only scenes from our theia sensor platform
  • Restricting the response to only scenes that intersect with a point located in the middle of Folsom Lake
  • Restricting the response to only scenes with less than or equal to 20% cloud coverage (cloud_coverage_lte)

I now have the Scene ID that I want to purchase and download – gE16fQt5RWepnz5nLGdxqg

Step 2: Ordering your scene

To simplify getting started with our Ordering APIs we’ve released an open source tool that assists you in the ecommerce workflow.

Instructions for installing and configuring the tool are available in the file. Once you’ve installed it, usage is as simple as the following:

$ python gE16fQt5RWepnz5nLGdxqg
Scene ID gE16fQt5RWepnz5nLGdxqg found. Captured by urthecast (theia sensor platform)
Created a new order with ID AVG2ZJOI7JuwutO9CY6L
Added line item for Scene ID gE16fQt5RWepnz5nLGdxqg to Order ID AVG2ZJOI7JuwutO9CY6L (estimated cost: 0)
Purchased order AVG2ZJOI7JuwutO9CY6L. Order is now in state processing.
Beginning to poll for order updates...
Order state is now delivered
Delivery AVG2bZHtf0HL8i7hzXxKis now ready.
URL for download:
Automatically Downloading...
100% [....................................................................] 2083275714 / 2083275714
Download now available at 2016-01-08_theia_0151b66499a8_00301783_003.tar.gz

Step 3: Extracting

Now that we’ve downloaded our GeoTIFF scene we can extract it:

$ tar xzvf 2016-01-08_theia_0151b66499a8_00301783_003.tar.gz 
x 2016-01-08_theia_0151b66499a8_00301783_003/red_2016-01-08_theia_0151b66499a8_00301783_003.TIF
x 2016-01-08_theia_0151b66499a8_00301783_003/metadata_2016-01-08_theia_0151b66499a8_00301783_003.json
x 2016-01-08_theia_0151b66499a8_00301783_003/green_2016-01-08_theia_0151b66499a8_00301783_003.TIF
x 2016-01-08_theia_0151b66499a8_00301783_003/near-ir_2016-01-08_theia_0151b66499a8_00301783_003.TIF
x 2016-01-08_theia_0151b66499a8_00301783_003/blue_2016-01-08_theia_0151b66499a8_00301783_003.TIF
x 2016-01-08_theia_0151b66499a8_00301783_003/LICENSE.txt

Step 4: Viewing

And, finally, we can now open any of those TIF files (I choose near-ir) in an application like QGIS (an open source GIS application) for easy viewing:

(C) Urthecast / Theia sensor

(C) Urthecast / Theia sensor

It looks like Folsom Lake in California has been hit pretty hard by the drought – those brightly-colored pixels surrounding the lake are indicative of freshly exposed soil.


The Ordering APIs are now available as an invite-only service, but will be made available to the general public in the coming months. If you haven’t yet made your account with UrtheCast, create one now. If you have more questions about getting access to our Ordering APIs, please get in touch with us. We are extremely excited about what our Ordering APIs will enable our customers to do and we plan to roll out additional functionality over the coming months.

We look forward to seeing what you build with the UrtheCast Platform.

Read NextArticles

Global Forest Watch

'UrtheCast offers a high-resolution view of the world's forests on Global Forest Watch'