{"_id":"5877b73ce1d2bd3d002a752c","category":{"_id":"58c81b5c6dc7140f003c3c46","__v":0,"project":"55faeacad0e22017005b8265","version":"55faeacad0e22017005b8268","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-03-14T16:33:32.348Z","from_sync":false,"order":8,"slug":"catalog-v2-guide","title":"Catalog V2 API Guide"},"__v":0,"project":"55faeacad0e22017005b8265","parentDoc":null,"user":"55fae9d4825d5f19001fa379","version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":37,"createdAt":"2015-09-17T16:31:06.800Z","releaseDate":"2015-09-17T16:31:06.800Z","categories":["55faeacbd0e22017005b8269","55faf550764f50210095078e","55faf5b5626c341700fd9e96","55faf8a7825d5f19001fa386","560052f91503430d007cc88f","560054f73aa0520d00da0b1a","56005aaf6932a00d00ba7c62","56005c273aa0520d00da0b3f","5601ae7681a9670d006d164d","5601ae926811d00d00ceb487","5601aeb064866b1900f4768d","5601aee850ee460d0002224c","5601afa02499c119000faf19","5601afd381a9670d006d1652","561d4c78281aec0d00eb27b6","561d588d8ca8b90d00210219","563a5f934cc3621900ac278c","5665c5763889610d0008a29e","566710a36819320d000c2e93","56ddf6df8a5ae10e008e3926","56e1c96b2506700e00de6e83","56e1ccc4e416450e00b9e48c","56e1ccdfe63f910e00e59870","56e1cd10bc46be0e002af26a","56e1cd21e416450e00b9e48e","56e3139a51857d0e008e77be","573b4f62ef164e2900a2b881","57c9d1335fd8ca0e006308ed","57e2bd9d1e7b7220000d7fa5","57f2b992ac30911900c7c2b6","58adb5c275df0f1b001ed59b","58c81b5c6dc7140f003c3c46","595412446ed4d9001b3e7b37","59e76ce41938310028037295","5a009de510890d001c2aabfe","5a96f89c89442e002041144b","5b3f9b7267cbc90003d283a5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-12T17:05:00.032Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Table of Contents\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Table of Contents\",\n    \"0-0\": \"[Catalog V2 API Overview](#section-catalog-v2-api-overview)\",\n    \"1-0\": \"[Catalog V2 API Base URI](#section-catalog-v2-api-base-url)\",\n    \"2-0\": \"[Catalog V2 API Requests](#section-catalog-v2-api-requests)\",\n    \"3-0\": \"[Records](#section-records)\",\n    \"4-0\": \"[Types](https://gbdxdocs.digitalglobe.com/docs/catalog-v2-course#section-types)\",\n    \"5-0\": \"[Searching the Catalog](#section-searching-the-catalog)\",\n    \"6-0\": \"[Search Results](#section-search-results)\",\n    \"7-0\": \"[IDAHO Image Results and Examples](#section-idaho-image-results-and-examples)\"\n  },\n  \"cols\": 1,\n  \"rows\": 8\n}\n[/block]\n# Catalog V2 API Overview\nThe Catalog V2 API offers fast querying capabilities and  data consistency. The API queries the GBDX Vector Services database. \n\nVector 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 . \n\n#  Catalog V2 API Base URl \n\n```https://geobigdata.io/catalog/v2```\n\n# Catalog V2 API Requests\n\nThe Catalog V2 API supportes the following requests:\n\nRequest Type | Request URL | Description | Try it Out\n--- | --- | --- | ---\n`GET` the API heartbeat | https://geobigdata.io/catalog/v2/heartbeat | Check the availability of the endpoint | [Catalog V2 Heartbeat](doc:catalog-heartbeat-v2) \n`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](doc:get-a-record-by-id) \n`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](doc:catalog-v2-search-by-spatial-area) \n\n\n# Records\nA \"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. \n\n#Types\nAll 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. \n\nFor example:\n * A search by types \"WV02\" would return WV02 acquisitions, WV02 1B products, and WV02 IDAHO Image products.\n\n* A search by types \"WV02\" and DigitalGlobeProduct\" will return WV02 1B products and WV02 IDAHO Image products.\n\n* A search by types \"WV02\" and \"1BProduct\" will return only WV02 1B products. \n\n### Search by Multiple Types\nIf a search by more than one type is executed, the records returned will match all of the types in the search query.\n\nFor example, a search for types \"WV03_SWIR\" and \"1BProduct\" will return all Worldview03 SWIR, 1B products that match the search criteria.\n\nHowever, a search for types \"WV02\" and \"WV03_SWIR\" will return 0 records,  because no record can match both of these criteria.\n\n## DigitalGlobe Acquisitions and Products Types\nIt's important to understand the difference between a DigitalGlobe Acquisition and a DigitalGlobeProduct.\n\n* 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. \n\n* A DigitalGlobe Product is a product made from an acquisition. If a product is cataloged on GBDX, the image is available. \n\n## List of Types\nType | Description \n--- | ---  \n1BProduct | Search by this type to find all 1B products from any DigitalGlobe sensor platform. \nAcquisition | The parent type for all acquisitions. . It's not necessary to include this type in a search.\nDigitalGlobeAcquisition | 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.\nDigitalGlobeProduct | 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.\nESAProduct | This type is the parent type for all SENTINEL records.\nGBDXCatalogRecord | This is the parent for all records cataloged by GBDX. It's not necessary to include this type in a search.\nGE01 | Search by this type to find imagery from the GeoEye-1 sensor platform.\nIDAHOImage | Search by this type to find all IDAHO images. \nIKONOS | Search by this type to find imagery from the IKONOS sensor platform.\nLandsat8 | Search by this type to find all imagery from the Landsat-8 sensor platform.\nLandsatAcquisition | The parent type for Landsat imagery.\nMDAProduct | This type indicates all product records from MDA data sources.\nQB02 | Search by this type to find imagery from the QuickBird-2 sensor platform.\nRADARSAT2 | This type indicates all records acquired from the RADARSAT-2 sensor platform\nSENTINEL2 | This type indicates all records acquired from the SENTINEL-2 satellite. \nSGFProduct | This type indicates the SAR Georeferenced Fine product. \nWV01 | Search by this type to find imagery from DigitalGlobe's Worldview-1 sensor platform.\nWV02 | Search by this type to find imagery from DigitalGlobe's Worldview-2 sensor platform.\nWV03_SWIR | Search by this type to find Short Wave Infrared (SWIR) imagery from DigitalGlobe's Worldview-3 sensor platform.\nWV03_VNIR | Search by this type to find Visible Near Infrared (VNIR) imagery from DigitalGlobe's Worldview-3 sensor platform.\n\n# Searching the Catalog\n\nUsing the Catalog V2 API, you can query by one or more of the following:\n\n* Empty search (no search criteria in the request)\n* Search by Spatial Area\n* Search by Date Range\n* Search by Type or multiple types\n* Search by Filter (searchable properties of a record)\n\nThe 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.\n\nYou can limit the number of results returned in the request body. See \"Limit search results returned\" below.\n\n## Spatial Area Search format\nThe 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.\n\n## Supported Date Formats\nThe following date formats are supported for the startDate and endDate.\n%Y-%m-%dTHH:MM:SS.000Z\n%Y-%m-%dTHH:MM:SSZ\n%Y-%m-%d\n%Y-%m-%dTHH:MM:SS\n\n## Limit search results returned\n\nThe 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:\n\n>\"limit\": 10\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"   {  \\n        \\\"searchAreaWkt\\\": \\\"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\\\",\\n        \\\"types\\\":[\\\"IDAHOImage\\\"],\\n        \\\"limit\\\":10\\n    }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n## Filters\nCatalog searches can include one or more \"filters.\" Filters are the record properties that are searchable. \n\n## Search Operators\n\n**Operator** | **Meaning** \n--- | --- \n> | Greater Than \n< | Less Than \n= | Equal To \n<= | Less Than or Equal To \n>= | Greater Than or Equal To \n<> | Not Equal \nlike*| search by partial string (used in a search by filter)\nor | return results with value1 OR value2\nand | return results with value1 AND value2\n\nWildcard 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. \n\n\"Between\" operator | The \"between\" operator is not supported for filtered searches. For example \"offNadirAngle between 1 and 10\" is not supported.\n\n## Sensor Platforms and Image Bands\n \nSensorPlatformName |ImageBands |Description\n--- | --- | ---\nGEOEYE01 | Pan_MS1 | Multispectral, 4-band\nIKONOS | Pan_MS1 | Panchromatic band, Multispectral 4-band\nQUICKBIRD02| Pan_MS1 |Multispectral, 4-band\nRADARSAT-2 | Beams in Extra-fine beam mode | Example: \"XF0W3\"\nSENTINEL2 | See bands description | CoastalAerosol\", \"Blue\", \"Green\", \"Red\", \"VegRedEdge5\", \"VegRedEdge6\", \"VegRedEdge7\", \"NIR\", \"VegRedEdge8a\", \"WaterVapor\", \"Cirrus\", \"SWIR11\", \"SWIR12\nWORLDVIEW01 |Pan |Black & White (Panchromatic)\nWORLDVIEW02 |Pan_MS1_MS2 | Multispectral, 8-band\nWORLDVIEW03_VNIR |  Pan_MS1_MS2| Multispectral, 8-band\nWORLDVIEW03_SWIR | SWIR 8-band | Shortwave infrared, 8-band\n \nProduct Type: Only Level 1B and IDAHOImage products are available in the GBDX catalog at this time. \n\nTo learn more about DigitalGlobe products and their specifications, see the <a href=\"https://dg-cms-uploads-production.s3.amazonaws.com/uploads/document/file/21/StandardImagery_DS_10-14_forWeb.pdf\" target=\"_blank\">DigitalGlobe Core Imagery Product Guide.</a>\n\n\n\n## Search Examples\n\nTo see search examples for each specific dataset, see the \"Datasets on GBDX\" information for each dataset.\n\n### Search by Type Example\nThis is an example of a \"search by type\" request within a defined search area. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"    {  \\n        \\\"searchAreaWkt\\\": \\\"POLYGON ((85.12055941 27.08074442, 85.31423408 27.10157442, 85.31502922 26.960545, 85.11922108 26.93735095, 85.12055941 27.08074442))\\\",\\n        \\\"startDate\\\":null,\\n        \\\"endDate\\\":null,\\n        \\\"types\\\":[\\\"DigitalGlobeProduct\\\"]\\n    }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n### Search by Multiple Types Example\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n \\t\\\"searchAreaWkt\\\": \\\"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\\\",\\n \\t\\\"startDate\\\": \\\"2014-01-01T00:00:00.000Z\\\",\\n \\t\\\"endDate\\\": \\\"2014-12-31T23:59:59.999Z\\\",\\n \\t\\\"types\\\": [\\\"WV03_VNIR\\\",\\n \\t\\t\\\"1BProduct\\\"\\n \\t]\\n }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n*Note: A search by multiple types will only return records that match all types included in the search request.*\n\n### Search by Filter example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n     \\t\\\"searchAreaWkt\\\": \\\"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\\\",\\n     \\t\\\"startDate\\\": \\\"2014-01-01T00:00:00.000Z\\\",\\n     \\t\\\"filters\\\": [\\\"cloudCover = '75'\\\"]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n### Search by Filter using partial string example\nThis 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.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"     {\\n     \\t\\\"searchAreaWkt\\\": \\\"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\\\",\\n     \\t\\\"startDate\\\": \\\"2014-01-01T00:00:00.000Z\\\",\\n     \\t\\\"filters\\\": [\\\"imageBands LIKE 'Pan_MS1*'\\\"]\\n     }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n# Search Results\n\nA search response body is made up of the following components:\n\nResponse section | Description\nStatistics | 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.\nIndividual records | The search results show all records returned by the search crtieria; up to 1000 records.\n\n## Statistics\n\n 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. \n\nStatistic | Description\n--- | ---\nrecordsReturned | This is the number of records in the response. \ntotalRecords | This is also the number of records in the response. See the \"note\" below.\ntypeCounts | This section shows the number of records by Type. A record typically has more than one type. \n\nThis  example is a response from a search request that looked for DigitalGlobeProducts. In this response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"stats\\\": {\\n    \\\"recordsReturned\\\": 358,\\n    \\\"totalRecords\\\": 358,\\n    \\\"typeCounts\\\": {\\n      \\\"WV02\\\": 154,\\n      \\\"WV01\\\": 140,\\n      \\\"DigitalGlobeProduct\\\": 358,\\n      \\\"GBDXCatalogRecord\\\": 358,\\n      \\\"GE01\\\": 24,\\n      \\\"1BProduct\\\": 358,\\n      \\\"WV03_VNIR\\\": 33,\\n      \\\"QB02\\\": 7\\n    }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nNote: recordsReturned and totalRecords currently show the same number. This is a known issue. \n\nSearch 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. \n   \n\n## Individual Records\n\nFollowing the statistics, each individual record is returned with its associated properties. Each record has 3 sections:\n\nRecord Section | Description\nidentifier | The identifier for that record. It could be a product ID, an IDAHOImage ID, or an acquisition ID.\ntype | all types associated with the individual record.\nproperties | The properties of a record are determined by its type. \n\n### Example record from a search results set:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"    {\\n          \\\"identifier\\\": \\\"LC80330322017024LGN00\\\",\\n          \\\"type\\\": [\\n            \\\"GBDXCatalogRecord\\\",\\n            \\\"Acquisition\\\",\\n            \\\"Landsat8\\\",\\n            \\\"LandsatAcquisition\\\"\\n          ],\\n          \\\"properties\\\": {\\n            \\\"vendor\\\": \\\"Landsat\\\",\\n            \\\"browseURL\\\": \\\"https://s3-us-west-2.amazonaws.com/landsat-pds/L8/033/032/LC80330322017024LGN00/LC80330322017024LGN00_thumb_large.jpg\\\",\\n            \\\"timestamp\\\": \\\"2017-01-24T17:37:24.000Z\\\",\\n            \\\"bucketPrefix\\\": \\\"L8/033/032/LC8033032201724LGN00\\\",\\n            \\\"footprintWkt\\\": \\\"MULTIPOLYGON(((-105.616 39.251, -105.616 41.38968, -102.9163 41.38968, -102.9163 39.251, -105.616 39.251)))\\\",\\n            \\\"cloudCover\\\": 75,\\n            \\\"catalogID\\\": \\\"LC80330322017024LGN00\\\",\\n            \\\"bucketName\\\": \\\"landsat-pds\\\",\\n            \\\"path\\\": 33,\\n            \\\"sensorPlatformName\\\": \\\"LANDSAT08\\\",\\n            \\\"multiResolution\\\": 30,\\n            \\\"row\\\": 32,\\n            \\\"platformName\\\": \\\"LANDSAT-8\\\",\\n            \\\"panResolution\\\": 15\\n          }\\n        }\\n    \",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nTo see the properties returned in a results set by data type, see the DataSets on GBDX section.\n\n[GeoEye-1](doc:geoeye-1) \n[IKONOS](doc:ikonos) \n[LANDSAT-8](doc:landsat-8) \n[MDA RADARSAT-2](doc:mda-radarsat-2) \n[QUICKBIRD](doc:quickbird) \n[Sentinel-2 (ESA)](doc:sentinel-2)\n[WORLDVIEW-1](doc:worldview-1) \n[WORLDVIEW-2](doc:worldview-2) \n[WORLDVIEW-3](doc:worldview-3)\n\n\n# IDAHO Image Results and Examples\n\n\n#### Example IDAHO Image Record ID\n>a4789af5-b7d7-49e2-93c6-72bc39292527\n\n#### Example Request for Worldview-2 IDAHO images over Denver\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"    {  \\n        \\\"searchAreaWkt\\\": \\\"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\\\",\\n        \\\"types\\\":[\\\"IDAHOImage\\\"],\\n        \\\"limit\\\":10\\n    }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Example Worldview-2 IDAHO Image record \n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" {\\n      \\\"identifier\\\": \\\"a4789af5-b7d7-49e2-93c6-72bc39292527\\\",\\n      \\\"type\\\": [\\n        \\\"GBDXCatalogRecord\\\",\\n        \\\"IDAHOImage\\\",\\n        \\\"DigitalGlobeProduct\\\",\\n        \\\"WV02\\\"\\n      ],\\n      \\\"properties\\\": {\\n        \\\"sunAzimuth\\\": 151.5,\\n        \\\"epsgCode\\\": \\\"4326\\\",\\n        \\\"cloudCover\\\": 0,\\n        \\\"numYTiles\\\": 21,\\n        \\\"numXTiles\\\": 35,\\n        \\\"imageWidth\\\": 8820,\\n        \\\"tileXOffset\\\": 0,\\n        \\\"tileYSize\\\": 256,\\n        \\\"idahoImageId\\\": \\\"a4789af5-b7d7-49e2-93c6-72bc39292527\\\",\\n        \\\"catalogID\\\": \\\"1030010027BFBF00\\\",\\n        \\\"vendorDatasetIdentifier\\\": \\\"LV1B:055673262010_01_P010:1030010027BFBF00:A010010207290700\\\",\\n        \\\"version\\\": \\\"1.0\\\",\\n        \\\"numBands\\\": 8,\\n        \\\"satAzimuth_dbl\\\": 102.5,\\n        \\\"offNadirAngle\\\": 43.2,\\n        \\\"platformName\\\": \\\"WORLDVIEW02\\\",\\n        \\\"vendorName\\\": \\\"DigitalGlobe\\\",\\n        \\\"imageHeight\\\": 5185,\\n        \\\"sunElevation\\\": 49.1,\\n        \\\"vendor\\\": \\\"DigitalGlobe\\\",\\n        \\\"acquisitionDate\\\": \\\"2013-09-17T17:41:04.566Z\\\",\\n        \\\"dataType\\\": \\\"UNSIGNED_SHORT\\\",\\n        \\\"timestamp\\\": \\\"2017-02-14T19:08:31.000Z\\\",\\n        \\\"tileYOffset\\\": 0,\\n        \\\"bucketName\\\": \\\"idaho-images\\\",\\n        \\\"tileXSize\\\": 256,\\n        \\\"colorInterpretation\\\": \\\"WORLDVIEW_8_BAND\\\",\\n        \\\"profileName\\\": \\\"dg_1b\\\",\\n        \\\"tilePartition\\\": \\\"0000\\\",\\n        \\\"groundSampleDistanceMeters\\\": 3.407,\\n        \\\"sensorName\\\": \\\"8-band (Coastal, Blue, Green, Yellow, Red, Red-edge, NIR1, NIR2) Multispectral\\\",\\n        \\\"tileBucketName\\\": \\\"idaho-images\\\",\\n        \\\"footprintWkt\\\": \\\"MULTIPOLYGON(((-105.09464988 39.62555901, -104.66370325 39.58173662, -104.66311767 39.45473852, -105.09410764 39.49707209, -105.09464988 39.62555901)))\\\",\\n        \\\"nativeTileFileFormat\\\": \\\"TIF\\\",\\n        \\\"pniirs\\\": 2.2,\\n        \\\"satElevation\\\": 39.8,\\n        \\\"sensorPlatformName\\\": \\\"WORLDVIEW02\\\"\\n      }\\n    }\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"catalog-v2-course","type":"basic","title":"Catalog V2 API Course"}

Getting Started

GBDX Operations

GBDX Stories

Data Sets on GBDX

Raster Data Access (RDA) Guide

GBDX Notebooks

Authentication Guide

Ordering Guide

Catalog V2 API Guide

Algorithms

Tasks and Workflows Guide

S3 Storage Service Guide

Web Application (Deprecated)

Thumbnail Service Guide (Deprecated)

AnswerFactory Application

Read & Query Vector Services Guide

Aggregations & Facets Vector Services Guide

Write & Ingest Vector Services Guide

Vector Export Service

IDAHO Guide

Helpful Links

Catalog V2 API Course

Table of Contents [block:parameters] { "data": { "h-0": "Table of Contents", "0-0": "[Catalog V2 API Overview](#section-catalog-v2-api-overview)", "1-0": "[Catalog V2 API Base URI](#section-catalog-v2-api-base-url)", "2-0": "[Catalog V2 API Requests](#section-catalog-v2-api-requests)", "3-0": "[Records](#section-records)", "4-0": "[Types](https://gbdxdocs.digitalglobe.com/docs/catalog-v2-course#section-types)", "5-0": "[Searching the Catalog](#section-searching-the-catalog)", "6-0": "[Search Results](#section-search-results)", "7-0": "[IDAHO Image Results and Examples](#section-idaho-image-results-and-examples)" }, "cols": 1, "rows": 8 } [/block] # 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](doc:catalog-heartbeat-v2) `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](doc: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](doc: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: [block:code] { "codes": [ { "code": " { \n \"searchAreaWkt\": \"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\",\n \"types\":[\"IDAHOImage\"],\n \"limit\":10\n }", "language": "json" } ] } [/block] ## 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 <a href="https://dg-cms-uploads-production.s3.amazonaws.com/uploads/document/file/21/StandardImagery_DS_10-14_forWeb.pdf" target="_blank">DigitalGlobe Core Imagery Product Guide.</a> ## 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. [block:code] { "codes": [ { "code": " { \n \"searchAreaWkt\": \"POLYGON ((85.12055941 27.08074442, 85.31423408 27.10157442, 85.31502922 26.960545, 85.11922108 26.93735095, 85.12055941 27.08074442))\",\n \"startDate\":null,\n \"endDate\":null,\n \"types\":[\"DigitalGlobeProduct\"]\n }", "language": "json" } ] } [/block] ### Search by Multiple Types Example [block:code] { "codes": [ { "code": "{\n \t\"searchAreaWkt\": \"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\",\n \t\"startDate\": \"2014-01-01T00:00:00.000Z\",\n \t\"endDate\": \"2014-12-31T23:59:59.999Z\",\n \t\"types\": [\"WV03_VNIR\",\n \t\t\"1BProduct\"\n \t]\n }", "language": "json" } ] } [/block] *Note: A search by multiple types will only return records that match all types included in the search request.* ### Search by Filter example [block:code] { "codes": [ { "code": "{\n \t\"searchAreaWkt\": \"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\",\n \t\"startDate\": \"2014-01-01T00:00:00.000Z\",\n \t\"filters\": [\"cloudCover = '75'\"]\n}", "language": "json" } ] } [/block] ### 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. [block:code] { "codes": [ { "code": " {\n \t\"searchAreaWkt\": \"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\",\n \t\"startDate\": \"2014-01-01T00:00:00.000Z\",\n \t\"filters\": [\"imageBands LIKE 'Pan_MS1*'\"]\n }", "language": "json" } ] } [/block] # 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: [block:code] { "codes": [ { "code": "{\n \"stats\": {\n \"recordsReturned\": 358,\n \"totalRecords\": 358,\n \"typeCounts\": {\n \"WV02\": 154,\n \"WV01\": 140,\n \"DigitalGlobeProduct\": 358,\n \"GBDXCatalogRecord\": 358,\n \"GE01\": 24,\n \"1BProduct\": 358,\n \"WV03_VNIR\": 33,\n \"QB02\": 7\n }", "language": "json" } ] } [/block] 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: [block:code] { "codes": [ { "code": " {\n \"identifier\": \"LC80330322017024LGN00\",\n \"type\": [\n \"GBDXCatalogRecord\",\n \"Acquisition\",\n \"Landsat8\",\n \"LandsatAcquisition\"\n ],\n \"properties\": {\n \"vendor\": \"Landsat\",\n \"browseURL\": \"https://s3-us-west-2.amazonaws.com/landsat-pds/L8/033/032/LC80330322017024LGN00/LC80330322017024LGN00_thumb_large.jpg\",\n \"timestamp\": \"2017-01-24T17:37:24.000Z\",\n \"bucketPrefix\": \"L8/033/032/LC8033032201724LGN00\",\n \"footprintWkt\": \"MULTIPOLYGON(((-105.616 39.251, -105.616 41.38968, -102.9163 41.38968, -102.9163 39.251, -105.616 39.251)))\",\n \"cloudCover\": 75,\n \"catalogID\": \"LC80330322017024LGN00\",\n \"bucketName\": \"landsat-pds\",\n \"path\": 33,\n \"sensorPlatformName\": \"LANDSAT08\",\n \"multiResolution\": 30,\n \"row\": 32,\n \"platformName\": \"LANDSAT-8\",\n \"panResolution\": 15\n }\n }\n ", "language": "json" } ] } [/block] 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) [MDA RADARSAT-2](doc:mda-radarsat-2) [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 [block:code] { "codes": [ { "code": " { \n \"searchAreaWkt\": \"POLYGON ((-105.35202026367188 39.48113956424843, -105.35202026367188 40.044848254075546, -104.65988159179688 40.044848254075546, -104.65988159179688 39.48113956424843, -105.35202026367188 39.48113956424843))\",\n \"types\":[\"IDAHOImage\"],\n \"limit\":10\n }", "language": "json" } ] } [/block] #### Example Worldview-2 IDAHO Image record [block:code] { "codes": [ { "code": " {\n \"identifier\": \"a4789af5-b7d7-49e2-93c6-72bc39292527\",\n \"type\": [\n \"GBDXCatalogRecord\",\n \"IDAHOImage\",\n \"DigitalGlobeProduct\",\n \"WV02\"\n ],\n \"properties\": {\n \"sunAzimuth\": 151.5,\n \"epsgCode\": \"4326\",\n \"cloudCover\": 0,\n \"numYTiles\": 21,\n \"numXTiles\": 35,\n \"imageWidth\": 8820,\n \"tileXOffset\": 0,\n \"tileYSize\": 256,\n \"idahoImageId\": \"a4789af5-b7d7-49e2-93c6-72bc39292527\",\n \"catalogID\": \"1030010027BFBF00\",\n \"vendorDatasetIdentifier\": \"LV1B:055673262010_01_P010:1030010027BFBF00:A010010207290700\",\n \"version\": \"1.0\",\n \"numBands\": 8,\n \"satAzimuth_dbl\": 102.5,\n \"offNadirAngle\": 43.2,\n \"platformName\": \"WORLDVIEW02\",\n \"vendorName\": \"DigitalGlobe\",\n \"imageHeight\": 5185,\n \"sunElevation\": 49.1,\n \"vendor\": \"DigitalGlobe\",\n \"acquisitionDate\": \"2013-09-17T17:41:04.566Z\",\n \"dataType\": \"UNSIGNED_SHORT\",\n \"timestamp\": \"2017-02-14T19:08:31.000Z\",\n \"tileYOffset\": 0,\n \"bucketName\": \"idaho-images\",\n \"tileXSize\": 256,\n \"colorInterpretation\": \"WORLDVIEW_8_BAND\",\n \"profileName\": \"dg_1b\",\n \"tilePartition\": \"0000\",\n \"groundSampleDistanceMeters\": 3.407,\n \"sensorName\": \"8-band (Coastal, Blue, Green, Yellow, Red, Red-edge, NIR1, NIR2) Multispectral\",\n \"tileBucketName\": \"idaho-images\",\n \"footprintWkt\": \"MULTIPOLYGON(((-105.09464988 39.62555901, -104.66370325 39.58173662, -104.66311767 39.45473852, -105.09410764 39.49707209, -105.09464988 39.62555901)))\",\n \"nativeTileFileFormat\": \"TIF\",\n \"pniirs\": 2.2,\n \"satElevation\": 39.8,\n \"sensorPlatformName\": \"WORLDVIEW02\"\n }\n }", "language": "json" } ] } [/block]