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:

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

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

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

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:

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.

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:

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