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. |
MODISProduct | All records acquired by the MODIS satellite |
QB02 | All acquisition and product records acquired by the QuickBird-2 satellite |
SENTINEL1 | All records acquired by the ESA's Sentinel-1 satellite |
SENTINEL2 | All records acquired by the EAS's SENTINEL-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 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* |
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
OR
OperatorThe 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
AND
OperatorThe 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](doc:geoeye-1)
[IKONOS](doc:ikonos)
[LANDSAT-8](doc:landsat-8)
[QUICKBIRD](doc:quickbird)
[Sentinel-2 (ESA)](doc:sentinel-2)
[WORLDVIEW-1](doc:worldview-1)
[WORLDVIEW-2](doc:worldview-2)
[WORLDVIEW-3](doc: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
```json
{
"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"
}
Updated about a year ago