{"_id":"56aa5dce09cb9c0d00f0c8c3","project":"55faeacad0e22017005b8265","version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":34,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"__v":34,"category":{"_id":"5601ae926811d00d00ceb487","pages":["561d51f56386060d00e06016","561d52469e8e1f0d00983290","561d527a31d9630d001eb5ce","561d52ef9e8e1f0d00983292","56411e7f2a2a4c0d00c69773","564a36d43242592b00338a74","566b368c1766bf0d00e73970","569805328d2a770d00d2fd3c","569806dd69393517000c846d","5698073e3503e40d0061f4f3","56aa5dce09cb9c0d00f0c8c3","56cf5b5f287eb20b009f9f26"],"project":"55faeacad0e22017005b8265","version":"55faeacad0e22017005b8268","__v":12,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-22T19:40:02.922Z","from_sync":false,"order":4,"slug":"ordering-guide","title":"Ordering Guide"},"parentDoc":null,"user":"55fae9d4825d5f19001fa379","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-28T18:28:30.614Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The GBDX Orders API lets you order imagery by catalog ID and check the status of your order. To place an order, you will POST a set of catalog IDs. The highest available resolution will be ordered. This includes the maximum number of bands, and both \"pan\" and \"multi\" resolution when both are available. The result will also include an order status and the S3 bucket location for each acquisition.\n\n\n\n\n\n# Orders V2 Overview\n\nVersion 2 of the GBDX ordering system provides big gains in performance, reliability, and ease of use. These improvements include:\n\n* The ability to place as many orders as you want, as quickly as you want. \n* New factory throttling guarantees we won't overload the DigitalGlobe (DG) factory. This means fewer ordering issues or failures for our customers.\n* No more duplicate orders. If a catalog ID has been ordered once, we won't order it again. \n* Simplified REST API. You'll use a single endpoint to place an order and check order status. API Responses have been simplified so you can quickly find the information you need.\n\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Ordering V2 uses order_ID instead of Sales_Order_Number.\"\n}\n[/block]\n## Order Limit\n Orders are limited to 100 catalog IDs per order requests. \n\n##Duplicates in an Order\nIf the same catalog ID is requested more than once in the same order request, they will be collapsed into one ID before the order is sent to the factory.\n\n## Authentication\nAll GBDX APIs require a token for authentication. See the [Authentication Course](doc:authentication-course) for more information.\n\n## SWIR imagery\nThe Ordering V2 API now supports ordering 7.5-meter SWIR acquisitions. If you have a SWIR catalog ID, you can order it.\n\nA SWIR catalog ID has an “A” in the 4th position instead of an “0”.\nStandard catalog ID: 104001000FA34F00\nSWIR catalog ID: 104A01000FA34F00 \n\n\n## Resources:\n\n__Resource__ | __Definition__ \n--- | --- \nHeartbeat | Verify the platform is responsive \nOrders | The resource for placing orders by catalog ID and getting the status of an order.\n\n\n##Place an Order\nTo place an order, POST a set of catalog IDs to https://geobigdata.io/orders/v2/order\n\nYour request will look like this:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n    \\\"104001000506EE00\\\",\\n    \\\"1010010005231400\\\"\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\nThe response will look like this: \n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"order_id\\\": \\\"ebffda38-1d6e-4fff-9ae2-aaca94243c45\\\",\\n  \\\"acquisitions\\\": [\\n    {\\n      \\\"acquisition_id\\\": \\\"1010010005231400\\\",\\n      \\\"state\\\": \\\"delivered\\\",\\n      \\\"location\\\": \\\"s3://receiving-dgcs-tdgplatform-com/055046034010_01_003\\\"\\n    },\\n    {\\n      \\\"acquisition_id\\\": \\\"104001000506EE00\\\",\\n      \\\"state\\\": \\\"delivered\\\",\\n      \\\"location\\\": \\\"s3://receiving-dgcs-tdgplatform-com/055046005010_01_003\\\"\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nItem | Description\n--- | ---\norder_id | The identifier given for the order. You'll use the order ID to check the status of your order.\nacquisition_id | The identifier for the ordered catalog ID. The response will include a line item for each catalog ID.\nstate | The order status of the catalog ID. See below for valid states and their definitions.\nS3 bucket location | When you order catalog IDs, the image files are placed in an Amazon Web Services S3 bucket. This is the bucket location. \n\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Keep track of your Order ID and S3 bucket location.\",\n  \"body\": \"You'll use the order ID to check the status of your order. You'll need the bucket location to access your data. Some tasks require the S3 bucket location as an input.\"\n}\n[/block]\nSee the [S3 Storage Service Course](doc:s3-storage-service-course) to learn how to access your AWS bucket.\n\n##Order States\n\nOrders can have the following states:\n\nOrder Status | Description\n--- | ---\nsubmitted | The order has been submitted to the GBDX platform\nordering | The Acquisition IDs are being ordered from the DigitalGlobe (DG) factory\nplaced | The order has been placed with the DG factory\ndelivered | The Acquisition ID has been delivered from the DG factory and is available\nfailed | The order failed. \n\n## Get an Order's Status\n\nTo get the status of an Order, send a GET request to https://geobigdata.io/orders/v2/order/<order_id>\n\nThe order_ID was provided when you placed the order. \n\nFor this example, we're looking for status of Order ID ebffda38-1d6e-4fff-9ae2-aaca94243c45. The response will look like this:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"order_id\\\": \\\"ebffda38-1d6e-4fff-9ae2-aaca94243c45\\\",\\n  \\\"acquisitions\\\": [\\n    {\\n      \\\"acquisition_id\\\": \\\"1010010005231400\\\",\\n      \\\"state\\\": \\\"delivered\\\",\\n      \\\"location\\\": \\\"s3://receiving-dgcs-tdgplatform-com/055046034010_01_003\\\"\\n    },\\n    {\\n      \\\"acquisition_id\\\": \\\"104001000506EE00\\\",\\n      \\\"state\\\": \\\"delivered\\\",\\n      \\\"location\\\": \\\"s3://receiving-dgcs-tdgplatform-com/055046005010_01_003\\\"\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n# Ordering with Callback Notifications\n\nThe Ordering with Callbacks API allows users to place an order and get a callback notification when the order has delivered or fails. The user submits an order with a URL in the JSON request. That url will receive the callback notification. \n\nThe callback notification is for the entire order. \n\nIf you don't need callback notifications, use the Orders V2 API.\n\n## Place an order with callback notifications\nTo place an order with callbacks, a POST request is submitted to:\n\n POST  to  https://geobigdata.io/orders/v2/ordercb \n\nThe JSON request body includes a set of acquisition IDs (CatIDs) and the URL to send the call back to.\n\nExample:\n\nJSON Request:\n\n    { \n      \"acquisitionIds\": [ \"CATID1\", \"CATID2\" ],\n      \"callback\": \"http://domainname.tld/callbackHandler\"\n    }\n\n\nJSON Response Body:\n\nWhen the order is submitted, the JSON response body will look like this:\n\n    {\n      \"order_id\": \"01af5259-64d9-4e16-a161-d6d5e6f3e958\",\n      \"acquisitions\": [\n        {\n          \"acquisition_id\": \"CATID1\",\n          \"state\": \"submitted\"\n        },\n        {\n          \"acquisition_id\": \"CATID2\",\n          \"state\": \"submitted\"\n        }\n      ],\n      \"callback\": \"http://domainname.tld/callbackHandler\"\n    }\n\n\n## States that trigger a callback notification\nThese states will deliver a callback notification for the entire order.\n* Delivered\n* Failed\nKeep track of your Order ID. You'll need it to check the order's status before the callback notification is sent.\n\n## Get Order Status\n\nTo see the status of an order places to the OrderCB API, with the order ID.\n\nSend a GET request to:\n\n GET   https://geobigdata.io/orders/v2/ordercb/<order_id> \n\n\n### Example 1: status = submitted\n\nThe JSON Response body will like this, with an updated order state.\n\n    {\n      \"order_id\": \"01af5259-64d9-4e16-a161-d6d5e6f3e958\",\n      \"acquisitions\": [\n        {\n          \"acquisition_id\": \"CATID1\",\n          \"state\": \"submitted\"\n        },\n        {\n          \"acquisition_id\": \"CATID2\",\n          \"state\": \"submitted\"\n        }\n      ]\n    }\n\n\n### Example 2: Status = \"ordering\"\n\n    {\n      \"order_id\": \"69cbf97a-8f98-46ae-8102-aef4541cb9fd\",\n      \"acquisitions\": [\n        {\n          \"acquisition_id\": \"10111111\",\n          \"state\": \"ordering\"\n        },\n        {\n          \"acquisition_id\": \"1022222\",\n          \"state\": \"ordering\"\n        }\n      ]\n    }\n\n\n\n\n\n#Get the S3 location of an Image\n\nThe /orders/v2/location endpoint lets you find the location of a DigitalGlobe acquisition without placing an order. Send a request to this endpoint with the catalog IDs in the query string.\n\n## Sample GET Request\n\nhttps://geobigdata.io/orders/v2/location?acquisitionIds=[\"CATID1\", \"CATID2\"]\n\nYou can list up to 100 catalog IDs in a single query. \n\n## Sample JSON Response\n\nThe response will look like this:\n\n    {\n      \"acquisitions\": [\n        {\n          \"acquisition_id\": \"CATID1\",\n          \"state\": \"delivered\",\n          \"location\": \"s3://bucket/prefix\"\n        },\n        {\n          \"acquisition_id\": \"CATID2\",\n          \"state\": \"not_found\",\n          \"location\": \"not_delivered\"\n        }\n      ]\n    }\n\n\nEach catalog ID in the request will be listed in the JSON response body with a \"state\" and a \"location.\"\n\nElement | Description\n--- | ---\nacquisition-id | This is the catalog ID for the image.\nstate | For each catalog ID, a state of either \"not_found\" or \"delivered\" will be returned. A state of \"not_found\" means the catalog ID has not been delivered yet. \nlocation | If the acquisition has been delivered, the s3 bucket location will be returned. If it hasn't been delivered, the location will be \"not_delivered.\"\n\nNote: This API endpoint returns the image location and delivery status only. It does not return order information or order status. To see a catalog ID's order status, see [Get Order Status v2](doc:get-order-status-v2). \n\n\n\n##API Reference Materials\n\n* [Orders Heartbeat v2](doc:orders-heartbeat-v2)\n* [Place an Order v2](doc:place-an-order-v2) \n* [Get Order Status v2](doc:get-order-status-v2)","excerpt":"Overview of DigitalGlobe's GBDX  Ordering system, version 2.","slug":"ordering-course-v2","type":"basic","title":"Ordering Course v2"}

Ordering Course v2

Overview of DigitalGlobe's GBDX Ordering system, version 2.

The GBDX Orders API lets you order imagery by catalog ID and check the status of your order. To place an order, you will POST a set of catalog IDs. The highest available resolution will be ordered. This includes the maximum number of bands, and both "pan" and "multi" resolution when both are available. The result will also include an order status and the S3 bucket location for each acquisition. # Orders V2 Overview Version 2 of the GBDX ordering system provides big gains in performance, reliability, and ease of use. These improvements include: * The ability to place as many orders as you want, as quickly as you want. * New factory throttling guarantees we won't overload the DigitalGlobe (DG) factory. This means fewer ordering issues or failures for our customers. * No more duplicate orders. If a catalog ID has been ordered once, we won't order it again. * Simplified REST API. You'll use a single endpoint to place an order and check order status. API Responses have been simplified so you can quickly find the information you need. [block:callout] { "type": "info", "title": "Ordering V2 uses order_ID instead of Sales_Order_Number." } [/block] ## Order Limit Orders are limited to 100 catalog IDs per order requests. ##Duplicates in an Order If the same catalog ID is requested more than once in the same order request, they will be collapsed into one ID before the order is sent to the factory. ## Authentication All GBDX APIs require a token for authentication. See the [Authentication Course](doc:authentication-course) for more information. ## SWIR imagery The Ordering V2 API now supports ordering 7.5-meter SWIR acquisitions. If you have a SWIR catalog ID, you can order it. A SWIR catalog ID has an “A” in the 4th position instead of an “0”. Standard catalog ID: 104001000FA34F00 SWIR catalog ID: 104A01000FA34F00 ## Resources: __Resource__ | __Definition__ --- | --- Heartbeat | Verify the platform is responsive Orders | The resource for placing orders by catalog ID and getting the status of an order. ##Place an Order To place an order, POST a set of catalog IDs to https://geobigdata.io/orders/v2/order Your request will look like this: [block:code] { "codes": [ { "code": "[\n \"104001000506EE00\",\n \"1010010005231400\"\n]", "language": "json" } ] } [/block] The response will look like this: [block:code] { "codes": [ { "code": "{\n \"order_id\": \"ebffda38-1d6e-4fff-9ae2-aaca94243c45\",\n \"acquisitions\": [\n {\n \"acquisition_id\": \"1010010005231400\",\n \"state\": \"delivered\",\n \"location\": \"s3://receiving-dgcs-tdgplatform-com/055046034010_01_003\"\n },\n {\n \"acquisition_id\": \"104001000506EE00\",\n \"state\": \"delivered\",\n \"location\": \"s3://receiving-dgcs-tdgplatform-com/055046005010_01_003\"\n }\n ]\n}", "language": "json" } ] } [/block] Item | Description --- | --- order_id | The identifier given for the order. You'll use the order ID to check the status of your order. acquisition_id | The identifier for the ordered catalog ID. The response will include a line item for each catalog ID. state | The order status of the catalog ID. See below for valid states and their definitions. S3 bucket location | When you order catalog IDs, the image files are placed in an Amazon Web Services S3 bucket. This is the bucket location. [block:callout] { "type": "warning", "title": "Keep track of your Order ID and S3 bucket location.", "body": "You'll use the order ID to check the status of your order. You'll need the bucket location to access your data. Some tasks require the S3 bucket location as an input." } [/block] See the [S3 Storage Service Course](doc:s3-storage-service-course) to learn how to access your AWS bucket. ##Order States Orders can have the following states: Order Status | Description --- | --- submitted | The order has been submitted to the GBDX platform ordering | The Acquisition IDs are being ordered from the DigitalGlobe (DG) factory placed | The order has been placed with the DG factory delivered | The Acquisition ID has been delivered from the DG factory and is available failed | The order failed. ## Get an Order's Status To get the status of an Order, send a GET request to https://geobigdata.io/orders/v2/order/<order_id> The order_ID was provided when you placed the order. For this example, we're looking for status of Order ID ebffda38-1d6e-4fff-9ae2-aaca94243c45. The response will look like this: [block:code] { "codes": [ { "code": "{\n \"order_id\": \"ebffda38-1d6e-4fff-9ae2-aaca94243c45\",\n \"acquisitions\": [\n {\n \"acquisition_id\": \"1010010005231400\",\n \"state\": \"delivered\",\n \"location\": \"s3://receiving-dgcs-tdgplatform-com/055046034010_01_003\"\n },\n {\n \"acquisition_id\": \"104001000506EE00\",\n \"state\": \"delivered\",\n \"location\": \"s3://receiving-dgcs-tdgplatform-com/055046005010_01_003\"\n }\n ]\n}", "language": "json" } ] } [/block] # Ordering with Callback Notifications The Ordering with Callbacks API allows users to place an order and get a callback notification when the order has delivered or fails. The user submits an order with a URL in the JSON request. That url will receive the callback notification. The callback notification is for the entire order. If you don't need callback notifications, use the Orders V2 API. ## Place an order with callback notifications To place an order with callbacks, a POST request is submitted to: POST to https://geobigdata.io/orders/v2/ordercb The JSON request body includes a set of acquisition IDs (CatIDs) and the URL to send the call back to. Example: JSON Request: { "acquisitionIds": [ "CATID1", "CATID2" ], "callback": "http://domainname.tld/callbackHandler" } JSON Response Body: When the order is submitted, the JSON response body will look like this: { "order_id": "01af5259-64d9-4e16-a161-d6d5e6f3e958", "acquisitions": [ { "acquisition_id": "CATID1", "state": "submitted" }, { "acquisition_id": "CATID2", "state": "submitted" } ], "callback": "http://domainname.tld/callbackHandler" } ## States that trigger a callback notification These states will deliver a callback notification for the entire order. * Delivered * Failed Keep track of your Order ID. You'll need it to check the order's status before the callback notification is sent. ## Get Order Status To see the status of an order places to the OrderCB API, with the order ID. Send a GET request to: GET https://geobigdata.io/orders/v2/ordercb/<order_id> ### Example 1: status = submitted The JSON Response body will like this, with an updated order state. { "order_id": "01af5259-64d9-4e16-a161-d6d5e6f3e958", "acquisitions": [ { "acquisition_id": "CATID1", "state": "submitted" }, { "acquisition_id": "CATID2", "state": "submitted" } ] } ### Example 2: Status = "ordering" { "order_id": "69cbf97a-8f98-46ae-8102-aef4541cb9fd", "acquisitions": [ { "acquisition_id": "10111111", "state": "ordering" }, { "acquisition_id": "1022222", "state": "ordering" } ] } #Get the S3 location of an Image The /orders/v2/location endpoint lets you find the location of a DigitalGlobe acquisition without placing an order. Send a request to this endpoint with the catalog IDs in the query string. ## Sample GET Request https://geobigdata.io/orders/v2/location?acquisitionIds=["CATID1", "CATID2"] You can list up to 100 catalog IDs in a single query. ## Sample JSON Response The response will look like this: { "acquisitions": [ { "acquisition_id": "CATID1", "state": "delivered", "location": "s3://bucket/prefix" }, { "acquisition_id": "CATID2", "state": "not_found", "location": "not_delivered" } ] } Each catalog ID in the request will be listed in the JSON response body with a "state" and a "location." Element | Description --- | --- acquisition-id | This is the catalog ID for the image. state | For each catalog ID, a state of either "not_found" or "delivered" will be returned. A state of "not_found" means the catalog ID has not been delivered yet. location | If the acquisition has been delivered, the s3 bucket location will be returned. If it hasn't been delivered, the location will be "not_delivered." Note: This API endpoint returns the image location and delivery status only. It does not return order information or order status. To see a catalog ID's order status, see [Get Order Status v2](doc:get-order-status-v2). ##API Reference Materials * [Orders Heartbeat v2](doc:orders-heartbeat-v2) * [Place an Order v2](doc:place-an-order-v2) * [Get Order Status v2](doc:get-order-status-v2)