Guides

Accessing Imagery

Suggest Edits

The goal of our data access API is to allow users to seamlessly integrate Albedo satellite data with the their workflows, processes, and applications.

For the remainder of this guide, we'll use two of the assets returned in the example searches from the Searching for Imagery guide to demonstrate how to access these assets in a variety of ways:

  • The view_ready_cog: /data/penns_landing_test/view_ready_cog/image.tif
  • The view_ready_tiles: /data/penns_landing_test/view_ready_tiles/{z}/{x}/{y}.png

Download an Asset

To download an asset, access the asset URL directly:

https://rest-api.albedodev.com/data/penns_landing_test/view_ready_cog/image.tif

Behind-the-scenes, this URL will return a redirect to a download link. So, if using an HTTP client, be sure to allow your HTTP client to follow redirects.

Here's an example using the ubiquitous cURL client:

curl -L --request GET \
     --url  https://rest-api.albedodev.com/data/penns_landing_test/view_ready_cog/image.tif \
     --header 'Authorization: Bearer <your bearer token>' > ~/penns_landing.tif

Beware that Albedo imagery is large, so downloads will take some time over a low-bandwidth network connection.

Stream a COG Asset

Our COG and COT assets support HTTP Range Request headers. This allows client applications to stream data from the asset as an alternative to downloading the asset in its entirety. Several geospatial imagery libraries and applications support interacting with COG assets in this way including:

Stream a Web Map Tile (XYZ) Asset

The asset URLs we publish in catalog item records are
XYZXYZ tile layers are a popular way to display map tiles in web mapping applications, such as OpenStreetMap, Google Maps, and Mapbox. The XYZ tile layer scheme divides the world into a grid of square tiles at a specific zoom level. Each tile is uniquely identified by its x, y, and z coordinates, where z represents the zoom level, x represents the column, and y represents the row of the tile in the grid.
templated URLs. For example, the URL for the view_ready_tiles asset for our Penn's Landing dataset is: 
https://rest-api.albedodev.com/data/penns_landing_test/view_ready_tiles/{z}/{x}/{y}.png
The {z},{x}, and {y}, elements should be replaced with actual
XYZ To determine the XYZ tile coordinates for your map, you'll need to take into account the zoom level of the map, the latitude and longitude of the area you want to display, and the size of the tiles you're using. Here are the steps to determine the XYZ tile coordinates:
  1. Determine the zoom level of your map. This is typically a number between 0 and 18, with higher numbers indicating a closer view of the map.
  2. Determine the latitude and longitude of the area you want to display on the map.
  3. Convert the latitude and longitude to pixel coordinates using a Mercator projection. There are many libraries and tools available that can do this for you. One such library is the OpenLayers library.
  4. Divide the pixel coordinates by the size of your tiles to get the tile coordinates. For example, if you're using 256x256 pixel tiles, and your pixel coordinates are (500, 700), your tile coordinates would be (1, 2) since 500/256=1.95 and 700/256=2.73, so you round to the nearest integer.
  5. Finally, append the zoom level to the tile coordinates to get the XYZ tile coordinates. For example, if your tile coordinates are (1, 2) and your zoom level is 5, your XYZ tile coordinates would be (5, 1, 2).
Note that there are many libraries and tools available that can help you with this process, and it's often easier to use an existing library or tool than to implement the calculations yourself.
map tile coordinates.

Note: Web map tile libraries and applications usually perform this function for the user. Our intent is that users can drop our templated URLs directly into those applications and the applications will do the rest.

To access a map tile directly, you can manually replace those elements with valid XYZ tile coordinates.

Updated over 1 year ago

What’s Next

For more information on the various formats mentioned above, please check out the following section