Intro to Worldview 2D Tasking
NOTE Tasking API V2 is in final development and review. This draft documentation is subject to change at any time.
Overview
The Tasking API lets you request a new imagery collection over your Area of Interest (AOI) within a specified time frame. You may include additional parameters such as image resolution and off-nadir angle. When a new image is collected, it is processed and delivered based on the instructions provided in your tasking request body.
Credits and usage
A usage quote is calculated when a request is submitted. The estimate is based on the tasking tier, image resolution, and whether the AOI falls in a low or high demand area. Account credits are reserved to cover the quoted amount. Once the order is fulfilled, any reserved credits that were not used are released.
Order size
The minimum order size for a tasking request is 50 sq kms. The maximum order size is 1000 sq kms.
High demand areas
High demand countries include: Armenia, Azerbaijan, Bahrain, Benin, China (East), Colombia, Congo, Cyprus, Ecuador, Gabon, Gaza Strip, Georgia, Iran, Iraq, Israel, Japan, Jordan, Kuwait, Lebanon, North Korea, Nigeria, Oman, Qatar, Saudi Arabia, Singapore, South Korea, Syria, Taiwan, Togo, Turkey, Turkmenistan, Ukraine, United Arab Emirates, West Bank, and Yemen
Tiers
Tasking is divided into tiers that balance priority and speed versus flexibility for collection options.
Fastview
Fastview guarantees collection on your specified date regardless of weather conditions. Within 24 hours of the requested start time, an image will be collected over your target area. The start date for a Fastview request must be at least 8 hours out and no further than 14 days from the date of submission.
A Fastview request is essentially a reservation for a 24 hour period. When the request is made, the requested start date is checked. If the date is available, the request is accepted. If the date is not available, the API returns a 400 response with a future available dates.
This tasking tier is ideal for time-sensitive missions when you need absolute certainty of collection.
Flexview
Optimized for weather conditions with cloud protection, Flexview ensures you get clear imagery that meets your specifications.
While Fastview is optimized for speed, with Flexview you have more flexibility to configure collection parameters. This means you can set limits to cloud cover, off-nadir angle, sun angle, and azimuth angle to get just the shot you want. Flexview also allows you to set custom polygon AOIs instead of the simplified target points used by Fastview.
Satellite assignment
When a tasking request is placed, the tasking system will dynamically assign the order to the best available sensor to meet the order criteria, including the WorldView Legion satellites. You cannot specify which satellite to task.
Quoting and placing Tasking orders
The following endpoints can be used to estimate tasking credit use, and to submit the tasking request:
| Request | Endpoint | Description |
|---|---|---|
| Quote a tasking order | /tasking/estimate | Returns estimate data for AOI sq kms and credits consumed for the request. |
| Submit a Flexview tasking order | /tasking/vantor | Submit your tasking request |
| Submit a Fastview tasking order | /tasking/vantor | Submit your tasking request |
| Validate a Tasking Request | /tasking/vantor?validation_only=true | add the path parameter validation_only=true to validate your request. For Fastview requests, you can use this parameter to check availability of your start date before submitting your request. |
See also the Flexview and Fastview examples.
Collection window (start and end date)
The collection window for the tasking request is determined by the start date submitted in the request. Flexview requires and end date to be set. Fastview has a set 24 hour collection window and does not accept an alternate end date. The start date for a Fastview request must be at least 8 hours out and no further than 13 days out.
| Tasking Tier | Start Time | End Time |
|---|---|---|
| Fastview | At least 8 hours into the future | Automatically expires in 24 hours |
| Flexview | At least 24 hours into the future | At most 364 days in the future |
Area of interest
AOIs vary based on tasking tier:
- Flexview: A polygon in GeoJSON format and that meets the minimum and maximum order size
- Fastview: A center point and one of four predefined buffer shapes.
Tasking parameters
The tasking parameters describe the conditions that must be met for the tasking order to be collected.
See the Flexview and Fastview parameter pages for a list of parameters for each tier.
Product options
Delivered images are processed using the Archive Imagery Pipeline.
Order deliveries
Once imagery is collected, ordered, and processed, it can be delivered to the following cloud storage platforms:
- Amazon S3 commercial cloud
- Azure cloud storage
- Google cloud storage
Tasking V2 does not currently support the download option but this delivery method is planned to be reinstated.
The order is also delivered to the Orders Manager in the Hub User Interface.
See Ordering Output Delivery Options for more detail.
Maximizing collection opportunities
The following recommendations will maximize the opportunity for a collection in your AOI within the requested date range:
Maximum cloud cover percentage: A low maximum cloud cover reduces the chances of an imagery collect, which means your request may take longer to fulfill. You can increase your collection opportunities by setting a higher cloud cover percentage. Imagery won't be collected when the cloud cover percentage is higher than 50%.
Maximum off-nadir angle (ONA) The off-nadir angle is how much the satellite’s camera is tilted when looking straight down. If the camera looks directly below the satellite, that’s called ‘nadir’ (0°). But if it’s angled to the side to capture an image farther away, that angle is the off-nadir angle.
An ONA of higher than 30 degrees will result in a higher than 30cm-class native GSD. As your ONA gets higher, your GSD will also get higher. For native 30cm-class imagery, your ONA must be equal to or less than 30 degrees for Worldview-3 and equal to or less than 24 degrees for Worldview Legion.
Target Azimuth Target azimuth is the direction the satellite is looking when it captures an image. It affects how the scene appears—things like the angle of buildings, the direction of shadows, and what features are more or less visible. Reducing your target azimuth will either reduce the number of access opportunities or shorten the length of the access window.
Sun Elevation Angle Sun Elevation Angle is the angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (15-90). Reducing the allowed sun elevation further may decrease your collection opportunities.
Managing Tasking orders
The following endpoints can be used to manage tasking orders:
| Request | Endpoint | Description |
|---|---|---|
| Get an existing tasking | /tasking/{id} | Returns an existing tasking by its ID. |
| List tasking orders | /tasking | List your tasking orders. Includes filtering and pagination. |
| Cancel tasking order | /tasking/cancel | Cancel a tasking request. |