GBDX

Catalog V2 API Course

Contents

Catalog V2 API Overview

The Catalog V2 API offers fast querying capabilities and data consistency. The API queries the GBDX Vector Services database.

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

Catalog V2 API Base URl

https://geobigdata.io/catalog/v2

Catalog V2 API Requests

The Catalog V2 API supportes the following requests:

Request Type Request URL Description Try it Out
GET the API heartbeat https://geobigdata.io/catalog/v2/heartbeat Check the availability of the endpoint Catalog V2 Heartbeat
GET a record by ID https://geobigdata.io/catalog/v2/record/recordID A record is the base data entity of the catalog. All product and acquisition types have a record ID. A record can be retrieved from the catalog by ID. Get a Record by ID
POST Search the catalog https://geobigdata.io/catalog/v2/search Search the catalog by area of interest, by date, and by type Catalog V2 Search by Spatial Area

Records

A "record" is an entry in the GBDX catalog. A record's properties are determined by its "type". For example, the properties for a Landsat8 record are different than those of an IDAHOImage record. A DigitalGlobe Acquisition record and a DigitalGlobe product record have different properties.

Types

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.

Search by Multiple Types

If a search by more than one type is executed, the records returned will match all of the types in the search query.

For example, a search for types "WV03_SWIR" and "1BProduct" will return all Worldview03 SWIR, 1B products that match the search criteria.

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

DigitalGlobe Acquisitions and Products Types

It's important to understand the difference between a DigitalGlobe Acquisition and a DigitalGlobeProduct.

  • A DigitalGlobe Acquisition is a capture from a DG sensor platform (Worldview-1, Worldview-2, Worldview-3, Quickbird-2, GeoEye-1). An acquisition is the raw data from the capture. It's not an image yet. GBDX catalogs the acquisition data. Not every acquisition has a product. When an acquisition is ordered through GBDX, a product is made and delivered.

  • A DigitalGlobe Product is a product made from an acquisition. If a product is cataloged on GBDX, the image is available.

List of Types

Type Description
1BProduct Search by this type to find all 1B products from any DigitalGlobe sensor platform.
Acquisition The parent type for all acquisitions. . It's not necessary to include this type in a search.
DigitalGlobeAcquisition The parent type for all DigitalGlobe Acquisitions. This type is useful for finding DG acquisitions from all DG sensor platforms, or to narrow the search results from a child type to include DigitalGlobe acquisitions, but not DigitalGlobe products.
DigitalGlobeProduct The parent type for all DigitalGlobe products. This type is useful for finding DG products from all DG sensor platforms, or to narrow the search results from a child type to include DigitalGlobe products, but not DigitalGlobe acquisitions. For example, to search for all products available from Worldview-2, include the type "DigitalGlobeProduct" and the type "WV02" in the search.
ESAProduct This type is the parent type for all SENTINEL records.
GBDXCatalogRecord This is the parent for all records cataloged by GBDX. It's not necessary to include this type in a search.
GE01 Search by this type to find imagery from the GeoEye-1 sensor platform.
IDAHOImage Search by this type to find all IDAHO images.
IKONOS Search by this type to find imagery from the IKONOS sensor platform.
Landsat8 Search by this type to find all imagery from the Landsat-8 sensor platform.
LandsatAcquisition The parent type for Landsat imagery.
MDAProduct This type indicates all product records from MDA data sources.
QB02 Search by this type to find imagery from the QuickBird-2 sensor platform.
RADARSAT2 This type indicates all records acquired from the RADARSAT-2 sensor platform
SENTINEL2 This type indicates all records acquired from the SENTINEL-2 satellite.
SGFProduct This type indicates the SAR Georeferenced Fine product.
WV01 Search by this type to find imagery from DigitalGlobe's Worldview-1 sensor platform.
WV02 Search by this type to find imagery from DigitalGlobe's Worldview-2 sensor platform.
WV03_SWIR Search by this type to find Short Wave Infrared (SWIR) imagery from DigitalGlobe's Worldview-3 sensor platform.
WV03_VNIR Search by this type to find Visible Near Infrared (VNIR) imagery from DigitalGlobe's Worldview-3 sensor platform.

Searching the Catalog

Using the Catalog V2 API, you can query by one or more of the following:

  • Empty search (no search criteria in the request)
  • Search by Spatial Area
  • Search by Date Range
  • Search by Type or multiple types
  • Search by Filter (searchable properties of a record)

The maximum number of records returned in any search is 1000. Pagination is not supported in the Catalog V2 API. If you need to see a larger set of results, you can query Vector Services directly.

You can limit the number of results returned in the request body. See "Limit search results returned" below.

Spatial Area Search format

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.

Supported Date Formats

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

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
    }

Filters

Catalog searches can include one or more "filters." Filters are the record properties that are searchable.

Search Operators

Operator Meaning
> Greater Than
< Less Than
= Equal To
<= Less Than or Equal To
>= Greater Than or Equal To
<> Not Equal
like* search by partial string (used in a search by filter)
or return results with value1 OR value2
and return results with value1 AND value2

Wildcard character | When executing a search using filters, the wildcard character is now an asterisk *. In catalog v1 it was a percent % sign. See "search by filter" example.

"Between" operator | The "between" operator is not supported for filtered searches. For example "offNadirAngle between 1 and 10" is not supported.

Sensor Platforms and Image Bands

SensorPlatformName ImageBands Description
GEOEYE01 Pan_MS1 Multispectral, 4-band
IKONOS Pan_MS1 Panchromatic band, Multispectral 4-band
QUICKBIRD02 Pan_MS1 Multispectral, 4-band
RADARSAT-2 Beams in Extra-fine beam mode Example: "XF0W3"
SENTINEL2 See bands description CoastalAerosol", "Blue", "Green", "Red", "VegRedEdge5", "VegRedEdge6", "VegRedEdge7", "NIR", "VegRedEdge8a", "WaterVapor", "Cirrus", "SWIR11", "SWIR12
WORLDVIEW01 Pan Black & White (Panchromatic)
WORLDVIEW02 Pan_MS1_MS2 Multispectral, 8-band
WORLDVIEW03_VNIR Pan_MS1_MS2 Multispectral, 8-band
WORLDVIEW03_SWIR SWIR 8-band Shortwave infrared, 8-band

Product Type: Only Level 1B and IDAHOImage products are available in the GBDX catalog at this time.

To learn more about DigitalGlobe products and their specifications, see the DigitalGlobe Core Imagery Product Guide.

Search Examples

To see search examples for each specific dataset, see the "Datasets on GBDX" information for each dataset.

Search by Type Example

This is an example of a "search by type" request within a defined search area.

    {  
        "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"]
    }

Search by Multiple Types 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": ["WV03_VNIR",
 		"1BProduct"
 	]
 }

Note: A search by multiple types will only return records that match all types included in the search request.

Search by Filter 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",
     	"filters": ["cloudCover = '75'"]
}

Search by Filter using partial string example

This partial string search will return all records with imageBands that start with PAN_MS1. So, it will return records with imageBands = PAN_MS1 or PAN_MS1_MS2.

     {
     	"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",
     	"filters": ["imageBands LIKE 'Pan_MS1*'"]
     }

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": "https://s3-us-west-2.amazonaws.com/landsat-pds/L8/033/032/LC80330322017024LGN00/LC80330322017024LGN00_thumb_large.jpg",
            "timestamp": "2017-01-24T17:37:24.000Z",
            "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"],
        "limit":10
    }

Example Worldview-2 IDAHO Image record

{
            "identifier": "0d79fc6e-85b6-493f-91a7-5abc4978cafa",
            "type": [
                "GBDXCatalogRecord",
                "IDAHOImage",
                "DigitalGlobeProduct",
                "WV01"
            ],
            "properties": {
                "satAzimuth": 256.2,
                "sunAzimuth": 167,
                "epsgCode": "4326",
                "cloudCover": 0,
                "numYTiles": 30,
                "numXTiles": 35,
                "imageWidth": 35180,
                "tileXOffset": 0,
                "tileYSize": 0,
                "idahoImageId": "0d79fc6e-85b6-493f-91a7-5abc4978cafa",
                "catalogID": "1020010005B22000",
                "vendorDatasetIdentifier": "LV1B:058162732010_01_P001:1020010005B22000:202001038FF35200",
                "version": "1.1",
                "numBands": 1,
                "offNadirAngle": 3.4,
                "platformName": "WORLDVIEW01",
                "vendorName": "DigitalGlobe, Inc.",
                "imageHeight": 29828,
                "sunElevation": 35.2,
                "vendor": "DigitalGlobe",
                "acquisitionDate": "2008-10-30T18:00:07.356Z",
                "dataType": "UNSIGNED_SHORT",
                "timestamp": "2008-10-30T18:00:07.356Z",
                "tileYOffset": 0,
                "bucketName": "rda-images-1",
                "tileXSize": 0,
                "colorInterpretation": "PAN",
                "profileName": "dg_1b",
                "tilePartition": "0000",
                "groundSampleDistanceMeters": 0.503,
                "sensorName": "Panchromatic",
                "tileBucketName": "rda-images-1",
                "footprintWkt": "MULTIPOLYGON(((-105.17393694 40.04757361, -104.96734324 40.04765137, -104.96754714 39.91420837, -105.1740042 39.91404878, -105.17393694 40.04757361)))",
                "nativeTileFileFormat": "PNG",
                "pniirs": 5,
                "satElevation": 86.2,
                "sensorPlatformName": "WORLDVIEW01"
            }
        }

Catalog V2 API Course