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

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` 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](ref: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](ref:search-the-catalog) 

## 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*|
|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](doc: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:

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:

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