GBDX

Catalog API Course

This document explains how imagery data is stored in the GBDX catalog and provides examples of how to search the catalog for imagery.

Last updated: October 8, 2019

Overview

The Catalog API is an interface that offers fast querying capabilities of the GBDX Vector Services Database. The API's endpoints let you find a single catalog record by ID or search the catalog for imagery records that meet the criteria you specify.

The Vector Services API that has additional capabilities that are not part of the Catalog API. To learn more, see http://gbdxdocs.digitalglobe.com/docs/vector-services-course .

All supported datasets on GBDX are searchable using the Catalog API. For a list of available datasets, see Datasets on GBDX .

Catalog Records

Individual entries in the Vector Services catalog are called records. Each record has a unique identifier and is associated with more than one "type." The information stored with each record depends on the "types" the record is associated with. For example, a DigitalGlobe Acquisition from Geoeye-1 will have different properties than a Landsat-8 record. A DigitalGlobe acquisition record and a DigitalGlobe product record have different properties, even though they are storing information about the same image.

Types

All catalog records are associated with the type "GBDXCatalogRecord." Additionally they are classified by types that provide further information about the record. Types can also tell us:

  • whether the record is an acquisition or a product (more on this later)
  • The type of acquisition or product (i.e. DigitalGlobe Product, LandsatAcquisition)
  • the source of the record

For example, a 1B product from the Worldview-3 VNIR sensor is associated with the following types:

  • GBDXCatalogRecord
  • GBDXProduct
  • 1BProduct
  • WORLDVIEW03_VNIR

Each of these types provides a subset of information that is stored with the record.

DigitalGlobe Acquisitions and Products Types

Images from DigitalGlobe satellites are cataloged as a either acquisitions or a products.

  • A DigitalGlobe Acquisition is the data collected for a capture from a DG sensor platform (Worldview-1, Worldview-2, Worldview-3, Worldview-4, Quickbird-2, GeoEye-1). GBDX catalogs the acquisition data and assigns it an ID.

  • DigitalGlobe products can be ordered using the GBDX Ordering API using the catalog ID for the acquisition. Once an order is placed, a product record is created and an order is sent to the DigitalGlobe factory. The product record has a product ID and the catalog ID it was ordered from.

The acquisition ID is also what we refer to as the "catalog ID." This is the unique identifier for the acquisition record. When a product record is created from the acquisition, it gets a product ID. That product ID is the unique identifier for the product record.

Types

Type Description
1BProduct All 1B products from any DigitalGlobe satellite
Acquisition An acquisition is the raw data collected from the satellite. Products are made from the acquisition data. This is the parent type for all acquisitions.
DigitalGlobeAcquisition All acquisition records from a DigitalGlobe satellite.
DigitalGlobeProduct All DigitalGlobe product records. . This includes 1B products and IDAHO images.
ESAProduct ESA is the abbreviation for the European Space Agency. This type includes all records from Sentinel satellites, which are part of the ESA's constellation.
GBDXCatalogRecord This is the parent for all records cataloged by GBDX. It's not necessary to include this type in a search.
GE01 Acquisition and product records from DigitalGlobe's GeoEye-1 satellite
IDAHOImage All IDAHO images
IKONOSAcquisition Imagery from DigitalGlobe's IKONOS satellite. All IKONOS records are cataloged as acquisitions, so searching by IKONOSAcquisition or IKONOS will return the same results.
IKONOS Imagery from DigitalGlobe's IKONOS satellite
Landsat8 All records from the Landsat-8 satellite
LandsatAcquisition All Landsat records. Currently GBDX only stores Landsat-8 data, so this type and the "Landsat8" type return the same results.
MDAAcquisition All acquisitions records acquired by MDA's Radarsat-2 satellite
MDAProduct All product records from MDA's Radarsat-2 satellite
MODISProduct All records acquired by the MODIS satellite
QB02 All acquisition and product records acquired by the QuickBird-2 satellite
RADARSAT2 All acquisitions and products from MDA's Radarsat-2 satellite
SENTINEL1 All records acquired by the ESA's Sentinel-1 satellite
SENTINEL2 All records acquired by the EAS's SENTINEL-2 satellite
SGFProduct This type indicates a SAR Georeferenced Fine product from MDA's Radarsat-2 satellite.
WV01 All acquisition and product records from DigitalGlobe's Worldview-1 satellite
WV02 All acquisition and product records from DigitalGlobe's Worldview-2 satellite
WV03_SWIR All Short Wave Infrared (SWIR) acquisition and product records from DigitalGlobe's Worldview-3 satellite
WV03_VNIR All Visible Near Infrared (VNIR) acquisition and product records from DigitalGlobe's Worldview-3 sensor platform
WV04 All acquisitions and IDAHO images acquired by DigitalGLobe's Worldview-4 satellite. Note: Worldview-4 1B products are not orderable on the GBDX platform and therefore are not cataloged on GBDX. Worldview-4 Idaho imagery is available through Raster Data Access (RDA) and through GBDX Notebooks.

Catalog API Endpoints

Base URL

The base url for the API is

https://geobigdata.io/catalog/v2

Authentication

A GBDX account and token are required to access to the Catalog API.

Headers

Authorization: Bearer {{token}}
Content-type: application/json

The Catalog API supports the following requests:

Request Type Request URL Description Try it Out
GET the API heartbeat /catalog/v2/heartbeat Check the availability of the endpoint. Catalog V2 Heartbeat
GET a record by ID /catalog/v2/record/recordID All product and acquisition types have a unique identifier, or "record ID." Append the record ID to this request in place of "record ID". Get a Record by ID
POST Search the catalog /catalog/v2/search Search the catalog by area of interest, by date, by type, and by filters. Catalog V2 Search by Spatial Area

Get a Record

To get the metadata for a specific record, make a Get a Record request using the record's unique identifier as the recordID.

Record Type Unique Identifier Example format
DigitalGlobe Acquisition DigitalGlobe Catalog ID 1050010016A5F000
1B Product DigitalGlobe Product Identifier 1030010098312600_P002_PAN_010754443010
IDAHO Image IDAHO Image ID 18103d7a-2ee4-4fde-b630-3cf4ce35709
IKONOS Catalog ID 2015011801450290000011603246
Landsat Product ID Collection 1 format = LC08_L1GT_096054_20190804_20190804_01_RT*
MDAAcquisition Catalog ID 431230_002
MDAProduct Product ID PDS_0653067
MODISProduct Catalog ID MOD09GQ.A2017122.h16v09.006.2017124032343
Sentinel 1 Catalog ID S1A_IW_GRDH_1SDV_20141207T041415_20141207T041440_003608_004445_556C
Sentinel 2 Identifier 10c3c634-599e-5d73-9b9a-2b662368f734

*Some older Landsat records from the precollection dataset use the catalog ID as the product ID. That format looks like:LC80960802019216LGN00.

Catalog ID and Product ID naming conventions are described on the individual dataset pages for each satellite. See Datasets on GBDX, and then select the dataset page you're looking for.

Search the Catalog

The Catalog API supports the following search criteria. Narrow your search results by including one or more of these:

  • Search by Spatial Area
  • Search by Date Range
  • Search by type or multiple types
  • Search by filter (searchable properties of a record) or multiple filters

Maximum Search Results Set

The maximum number of records returned in any search is 1000. Pagination is not supported in the Catalog API. If you need to see a larger set of results, you can query Vector Services directly.
To see a smaller results set, set a limit for the number of results returned. See "Limit search results returned" below.

Example: Search by all criteria

This is an example of a search that uses all of the criteria and then limits the size of the results set. Searches can include one or more of these criteria.

    {
         "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
         "startDate": "2014-01-01T00:00:00.000Z",
         "endDate": "2014-12-31T23:59:59.999Z",
         "filters": ["(sensorPlatformName = WORLDVIEW03_VNIR) OR (sensorPlatformName = WORLDVIEW03_SWIR)"],
         "types": ["1BProduct"],
         "limit": 3
     }

Search by Spatial Area

The well known text (wkt) POLYGON is used for searchAreaWkt searches. Other geometry types are not supported. MULTIPOLYGON geometry type searches are not currently supported. These searches will return a 400 response code.

Example: Search by Spatial Area

    {
     "searchAreaWkt": "POLYGON ((-122.41189956665039 37.59415685597818, -122.41189956665039 37.64460175855099, -122.34529495239259 37.64460175855099, -122.34529495239259 37.59415685597818, -122.41189956665039 37.59415685597818))",
     "startDate": null,
     "endDate": null,
     "limit": 3  
    }

Search by Date Range

The following date formats are supported for the startDate and endDate.
%Y-%m-%dTHH:mm:SS.000Z
%Y-%m-%dTHH:mm:SSZ
%Y-%m-%d
%Y-%m-%dTHH:mm:SS

As a best practice, we recommend including both a start date and an end date to execute a date range search. It is possible, however, to use only one or the other. Using "start date" alone will return all relevant records with a time stamp from the start date forward. Using "end date" only will return all relevant records with a date prior to the specified end date.

Example: Search by Date Range

    {
        "searchAreaWkt": null,
        "startDate": "2018-06-01T12:00:00.000Z",
        "endDate": "2018-06-06T12:00:00.000Z",
        "limit": 3
    }

Limit search results returned

The number of search results returned in a query can be limited. To do this, add the "limit" field to the search request body, like this:

"limit": 10

Example:

     {  
         "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
         "types":["IDAHOImage"],
         "limit":10
     }

Search by a single Type

All records in the GBDX catalog have one or more "types." The catalog can be searched by a single type or by multiple types. Use the most specific type possible to narrow your search results.

For example:

  • A search by types "WV02" would return WV02 acquisitions, WV02 1B products, and WV02 IDAHO Image products.
  • A search by types "WV02" and DigitalGlobeProduct" will return WV02 1B products and WV02 IDAHO Image products.

  • A search by types "WV02" and "1BProduct" will return only WV02 1B products.

Examples: Search by a single type

     {  
           "searchAreaWkt": "POLYGON ((85.12055941 27.08074442, 85.31423408 27.10157442, 85.31502922 26.960545, 85.11922108 26.93735095, 85.12055941 27.08074442))",
           "startDate":null,
           "endDate":null,
           "types":["DigitalGlobeProduct"],
           "limit":5
     }
Search by type using a partial string search

An asterisk * can be used to execute a partial string type search. For example, the following search will return results associated with types WV03_VNIR and WV03_SWIR.

     {
         "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
         "startDate": "2017-01-01T00:00:00.000Z",
         "endDate": "2018-09-01T23:59:59.999Z",
          "types": ["WV03*"],
      }

Search by multiple types

A search by multiple types can be executed using either the OR or the AND operator. The recommend format is:

"types": ["type 1 OPERATOR type 2"]

For example:

"types": ["WV02 AND DigitalGlobeProduct"]

"types": ["WV02 OR WV03_VNIR"]

The operators OR and AND must be uppercase.

OR Operator

The OR operator will return all records that match either type 1 or type 2.

In this example, "types": ["WV02 OR WV03_VNIR"]

all records associated with either WV02 or WV03_VNIR types will be returned.

AND Operator

The AND operator will return all records that match both type 1 and type 2.

In this example, ``"types": ["WV02 AND DigitalGlobeProduct"]```

all records that are associated with both WV02 and DigitalGlobeProduct types will be returned.

However, a search for types "WV02" and "WV03_SWIR" will return 0 records, because no record can match both of these criteria.

Multiple types search example

     {
          "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
          "startDate": "2014-01-01T00:00:00.000Z",
          "endDate": "2014-12-31T23:59:59.999Z",
          "types": ["WV02 AND DigitalGlobeProduct"]
     }

Filter by Properties

Search results can be filtered by most of the properties of a record. For example, you can filter search results by:

  • cloud cover
  • sun elevation
  • off nadir angle
  • Specific catalog ID or product ID

You can search by one filter or multiple filters.

Filter by a single property

Searching by a filter requires the name of the property, an operator, and a value.

     "filters": ["property name OPERATOR value"]`

Example:

     "filters": ["cloudCover < 20"]`

Search Operators

The following operators can be used in a single filter search:

Operator Description Value type
> Greater Than Numerical
< Less Than Numerical
= Equal To Numerical, String
<= Less Than or Equal To Numerical
>= Greater Than or Equal To Numerical
<> Not Equal Numerical, String
* Use the asterisk to search by a partial string Numerical, String

Single filter search examples

Filter by cloud cover

This example shows how to filter out records where the cloud cover is less than 20% .

     {
         "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
         "startDate": "2017-01-01T00:00:00.000Z",
         "endDate": "2018-09-01T23:59:59.999Z",
          "types": ["1BProduct"],
          "filters": ["cloudCover < 20"]
     }
Filter by Catalog ID

A search by catalog ID for a DigitalGlobe image with no additional criteria will return the following, if all are available in the catalog:

  • The acquisition record for the catalog ID
  • Each DigitalGlobe product associated with that catalog ID. Products can have multiple parts, and each part is associated with the catalog ID for the acquisition record. This means that a search by catalog ID may return multiple product records. The DigitalGlobe products returned can be either 1B products or IDAHO images.
     {"filters": ["catalogID = 1050010018826700"]}

To get only records of a specific type for that catalog ID, add "types" to your search criteria.

For example, to get only the acquisition record for that catalog ID, add the type "acquisition."

     {
       "types": ["Acquisition"],
       "filters": ["catalogID = 1050010018826700"]
     }

If you are working with Idaho Images and want to see all the parts of the IDAHO Image tile for the catalog ID, use this search example:

     {
       "types": ["IDAHOImage"],
       "filters": ["catalogID = 1050010018826700"]
     }
Filter by Product ID

If you have a product ID, you can use filtering to find the records associated with it.

This example searches for a Landsat-8 product ID.

    {
       "filters": ["productID = LC08_L1TP_034032_20181102_20181115_01_T1"]
    }

Filter by multiple properties

You can filter your search results by multiple properties in a single request. For example, you may want to find all imagery from a specific satellite with less than 20 percent cloud cover and an off nadir angle of less than 10 degrees.

In this example, the search request is looking for 1B products from the specified area within the date range of January 1, 2017 to December 31, 2018. The search results are further filtered to show only WV03_VNIR and WV03_SWIR records with less than 20% cloud cover and an off nadir angle of less than 10 degrees.

    {
         "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
         "startDate": "2017-01-01T00:00:00.000Z",
         "endDate": "2018-09-01T23:59:59.999Z",
         "types": ["1BProduct"],
         "filters": ["sensorPlatformName = WORLDVIEW03* AND cloudCover < 20 AND offNadirAngle < 10"]
     }

Filter by a partial string using a wildcard character

The Catalog API accepts an asterisk * as a wildcard character. This allows you to search for a partial string.

Searching for Worldview-3 imagery is an example of where a partial string search may be useful. In the GBDX catalog, Worldview-3 imagery is grouped by VNIR or SWIR imagery.

The "types" for Worldview-3 imagery are:

  • WV03_VNIR
  • WV03_SWIR

The sensor platform name properties for Worldview-3 are:

  • WORLDVIEW03_VNIR
  • WORLDVIEW03_SWIR

One way to find all Worldview-3 records in a single search is to use multiple filters with an OR operator.

    {
     "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
     "startDate": "2017-01-01T00:00:00.000Z",
     "endDate": "2074-12-31T23:59:59.999Z",
     "filters": ["(sensorPlatformName = WORLDVIEW03_VNIR) OR (sensorPlatformName = WORLDVIEW03_SWIR)"]
    }

You can achieve the same results with a partial string search using an asterisk * as a wildcard.

     {
      "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
      "startDate": "2017-01-01T00:00:00.000Z",
      "endDate": "2074-12-31T23:59:59.999Z",
      "filters": ["(sensorPlatformName = WORLDVIEW03*)"] 
     }

Search Results

A search response body is made up of the following components:

Response section Description
Statistics The statistics at the top of the search results set show the total number of records, and the number of records by type. The types listed in the statistics are those associated with at least one record in the results.
Individual records The search results show all records returned by the search crtieria; up to 1000 records.

Statistics

The response body from a catalog search begins with a statistics section. This section describes the records set included in the response. The statistics section is the same for all record types.

Statistic Description
recordsReturned This is the number of records in the response.
totalRecords This is also the number of records in the response. See the "note" below.
typeCounts This section shows the number of records by Type. A record typically has more than one type.

This example is a response from a search request that looked for DigitalGlobeProducts. In this response:

    {
  "stats": {
    "recordsReturned": 358,
    "totalRecords": 358,
    "typeCounts": {
      "WV02": 154,
      "WV01": 140,
      "DigitalGlobeProduct": 358,
      "GBDXCatalogRecord": 358,
      "GE01": 24,
      "1BProduct": 358,
      "WV03_VNIR": 33,
      "QB02": 7
    }

Note: recordsReturned and totalRecords currently show the same number. This is a known issue.

Search results are always limited to 1000 records. When the number of records in a response hits this limit, both statistics will show the number 1000. If you add a "limit" to your search request, both numbers will show that limit.

Individual Records

Following the statistics, each individual record is returned with its associated properties. Each record has 3 sections:

Record Section Description
identifier The identifier for that record. It could be a product ID, an IDAHOImage ID, or an acquisition ID.
type all types associated with the individual record.
properties The properties of a record are determined by its type.

Example record from a search results set:

    {
          "identifier": "LC80330322017024LGN00",
          "type": [
            "GBDXCatalogRecord",
            "Acquisition",
            "Landsat8",
            "LandsatAcquisition"
          ],
          "properties": {
            "vendor": "Landsat",
            "browseURL": "full path browse url",
            "bucketPrefix": "L8/033/032/LC8033032201724LGN00",
            "footprintWkt": "MULTIPOLYGON(((-105.616 39.251, -105.616 41.38968, -102.9163 41.38968, -102.9163 39.251, -105.616 39.251)))",
            "cloudCover": 75,
            "catalogID": "LC80330322017024LGN00",
            "bucketName": "landsat-pds",
            "path": 33,
            "sensorPlatformName": "LANDSAT08",
            "multiResolution": 30,
            "row": 32,
            "platformName": "LANDSAT-8",
            "panResolution": 15
          }
        }

To see the properties returned in a results set by data type, see the DataSets on GBDX section.

GeoEye-1
IKONOS
LANDSAT-8
MDA RADARSAT-2
QUICKBIRD
Sentinel-2 (ESA)
WORLDVIEW-1
WORLDVIEW-2
WORLDVIEW-3

IDAHO Image Results and Examples

Example IDAHO Image Record ID

a4789af5-b7d7-49e2-93c6-72bc39292527

Example Request for Worldview-2 IDAHO images over Denver

  {  
        "searchAreaWkt": "POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))",
        "types":["(IDAHOImage) AND (WV02)"],
        "limit":10
    }

Example Worldview-2 IDAHO Image record

  {
            "identifier": "5ab75271-020c-42f4-a8c4-d109ca345937",
            "type": [
                "GBDXCatalogRecord",
                "IDAHOImage",
                "DigitalGlobeProduct",
                "WV02"
            ],
            "properties": {
                "satAzimuth": 211.9,
                "sunAzimuth": 159.2,
                "epsgCode": "4326",
                "cloudCover": 0,
                "numYTiles": 10,
                "numXTiles": 35,
                "imageWidth": 35180,
                "tileXOffset": 0,
                "tileYSize": 0,
                "idahoImageId": "5ab75271-020c-42f4-a8c4-d109ca345937",
                "catalogID": "103001007B54D400",
                "vendorDatasetIdentifier": "LV1B:057710103010_01_P011:103001007B54D400:A01001035C17C800",
                "version": "1.0",
                "numBands": 1,
                "offNadirAngle": 22.0,
                "platformName": "WORLDVIEW02",
                "vendorName": "DigitalGlobe, Inc.",
                "imageHeight": 9220,
                "sunElevation": 46.2,
                "vendor": "DigitalGlobe",
                "acquisitionDate": "2018-03-15T18:10:51.637Z",
                "dataType": "UNSIGNED_SHORT",
                "timestamp": "2018-03-15T18:10:51.637Z",
                "tileYOffset": 0,
                "bucketName": "rda-images-1",
                "tileXSize": 0,
                "colorInterpretation": "PAN",
                "profileName": "dg_1b",
                "tilePartition": "0000",
                "groundSampleDistanceMeters": 0.536,
                "sensorName": "Panchromatic",
                "tileBucketName": "rda-images-1",
                "footprintWkt": "MULTIPOLYGON(((-104.84379818 40.02045088, -104.62786842 40.03596411, -104.62840823 39.99064667, -104.84334027 39.97573232, -104.84379818 40.02045088)))",
                "nativeTileFileFormat": "PNG",
                "pniirs": 4.9,
                "satElevation": 65.0,
                "sensorPlatformName": "WORLDVIEW02"
            }

Catalog API Course


This document explains how imagery data is stored in the GBDX catalog and provides examples of how to search the catalog for imagery.

Last updated: October 8, 2019

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.