Getting Started
Last updated: June 5, 2024
Welcome to the eAPI Quick Start guide!¶
The Enhanced API (eAPI) offers access to Maxar's System Ready 1B (basic level-unprocessed) imagery products. To learn more about the Maxar eAPI, see about eAPI.
This Quick Start example will walk you through searching and ordering 1B imagery by making API calls. The orders are saved to the cloud storage platform during the ordering process. At the moment, eAPI only supports saving deliveries to Amazon Web Service's S3.
Steps¶
1. Obtain an account¶
The first thing you will need to do is request an account by submitting your request to the eapisupport@maxar.com. If you are a US Government contractor ensure your Government point of contact is aware as they will be contacted during the registration process for validation and approval. Once you have been approved you will receive an e-mail from our Mission Support Team providing you details on the process for setting up your account.
The e-mail you receive from the Mission Support Team will provide you with a temporary password. The first step in setting up your account will be to change your password. This will need to be done in order to be granted access. To do so will require logging into the eAPI's authorization provider to modify your account settings.
2. Generate an authorization token¶
Once you have logged in and changed your password you will be able to generate an authorization token using the authorization provider's endpoint. You will need to provide your username and password to receive a token.
Example using cURL
curl https://keycloak.eapi.maxar.com/realms/general/protocol/openid-connect/token --data "username=your_user_name&password=your_password&grant_type=password&client_id=access"
The Enhanced API uses an OAuth access token for authentication. To request a token, you'll send your eAPI username (email address you registered with) and password to the "token" endpoint. Tokens expire after twelve hours and must be requested again.
The token you receive will be need to be appended to each request sent to the eAPI REST endpoints. This token will be in the form of a bearer token. The sections below will illustrate how to do this.
For detailed information on requesting a token, see the Getting an access token user guide.
Note: Keep in mind S3 buckets are not required for searching. You can skip to Step 4 below if you don't have a S3 bucket. However, a S3 bucket will be required for ordering imagery.
3. Set up a S3 Bucket Policy to give eAPI write access¶
- Create an AWS bucket for delivery if you don't already have one. You can create a new bucket from the AWS Management Console.
- Add a bucket policy that gives eAPI permission to write data to your bucket.
Note: The policy only needs to be set up once on a bucket. Maxar's permissions can be revoked by deleting the policy or editing it to deny access.
For detailed information on adding the policy, view the Setting up a S3 Bucket Policy user guide.
4. Conduct a search¶
View the Search endpoints here: https://eapi.maxar.com/e1so/rapidoc#get-/search
eAPI's Searching capability leverages Maxar's Discovery REST API to search for imagery.
We are going to do a search for the latest WorldView-2 satellite image. The request will not include any parameters such as bounding box, date range, or cloud cover restrictions. We just want to obtain the latest image taken by the satellite.
We will be using cURL to conduct the search and will need to include the token you received above as a header parameter in the request.
For detailed information on eAPI's searching capability view the Searching user guide.
4a. Run the cURL command below (search):¶
GET
curl -X GET "https://eapi.maxar.com/e1so/search?collections=wv02&limit=1&page=1" \
-H "Accept: application/json" \
-H "Authorization: Bearer <ADD_YOUR_ACCESS_TOKEN>"
4b. Results¶
{
"type": "FeatureCollection",
"features": [
{
"id": "10300100E06D7600",
"bbox": [
88.389660996,
-75.016754242,
89.210032925,
-73.979412702
],
"type": "Feature",
"links": [
{
"rel": "collection",
"href": "https://api.content.maxar.com/catalog/collections/wv02",
"type": "application/json"
},
{
"rel": "root",
"href": "https://api.content.maxar.com/catalog/collections/dg-archive",
"type": "application/json"
},
{
"rel": "self",
"href": "https://api.content.maxar.com/catalog/collections/wv02/items/10300100E06D7600",
"type": "application/geo+json"
}
],
"assets": {
"browse": {
"href": "https://api.content.maxar.com/catalog/collections/wv02/items/10300100E06D7600/assets/collections/dg-archive/assets/browse/10300100E06D7600.browse.tif",
"type": "image/tiff; application=geotiff",
"title": "Browse Image"
},
"cloud-cover": {
"href": "https://api.content.maxar.com/catalog/collections/wv02/items/10300100E06D7600/assets/collections/wv02/assets/cloud-cover/10300100E06D7600.cloud.json",
"type": "application/geo+json",
"title": "Cloud Cover"
},
"sample-point-set": {
"href": "https://api.content.maxar.com/catalog/collections/wv02/items/10300100E06D7600/assets/collections/wv02/assets/sample-point-sets/10300100E06D7600.sample-points.json",
"type": "application/geo+json",
"title": "Sample Point Set"
}
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
89.210032925,
-73.979412702
],
[
88.390377277,
-73.98894367
],
[
88.390498749,
-74.024888314
],
[
88.390583258,
-74.076090485
],
[
88.390669521,
-74.127181875
],
[
88.390720595,
-74.178170246
],
[
88.390809678,
-74.229068944
],
[
88.390851977,
-74.27986736
],
[
88.390785561,
-74.33056863
],
[
88.390721027,
-74.381183184
],
[
88.390724264,
-74.431695541
],
[
88.390700542,
-74.482139042
],
[
88.390661711,
-74.532471013
],
[
88.390638177,
-74.582731112
],
[
88.390585827,
-74.632912296
],
[
88.390444151,
-74.682984971
],
[
88.390354992,
-74.732996954
],
[
88.390349598,
-74.78292993
],
[
88.390242538,
-74.832796599
],
[
88.390033003,
-74.882574877
],
[
88.389902205,
-74.932296346
],
[
88.38976752,
-74.981934548
],
[
88.389660996,
-75.015553448
],
[
89.204896396,
-75.016754242
],
[
89.205012649,
-74.982882742
],
[
89.205135282,
-74.932775577
],
[
89.205271781,
-74.882577879
],
[
89.205525219,
-74.832316364
],
[
89.205708309,
-74.781959633
],
[
89.205854592,
-74.731530235
],
[
89.206085391,
-74.681014167
],
[
89.206369003,
-74.630430936
],
[
89.206585837,
-74.579732353
],
[
89.206778827,
-74.528947157
],
[
89.20700735,
-74.47808392
],
[
89.207240509,
-74.427101665
],
[
89.207497224,
-74.376042402
],
[
89.207828598,
-74.324874153
],
[
89.208191916,
-74.273610652
],
[
89.208472962,
-74.222242578
],
[
89.208725805,
-74.170766769
],
[
89.209066903,
-74.119192694
],
[
89.209444003,
-74.067506092
],
[
89.209804293,
-74.015701406
],
[
89.210032925,
-73.979412702
]
]
]
},
"collection": "wv02",
"properties": {
"gsd": 0.6317207254545455,
"title": "Maxar WV02 Image 10300100E06D7600",
"datetime": "2022-12-29T19:46:36.214951Z",
"eo:bands": [
{
"name": "pan",
"center_wavelength": 625
},
{
"name": "nir2",
"center_wavelength": 950
},
{
"name": "nir1",
"center_wavelength": 895
},
{
"name": "red_edge",
"center_wavelength": 725
},
{
"name": "red",
"center_wavelength": 660
},
{
"name": "yellow",
"center_wavelength": 605
},
{
"name": "green",
"center_wavelength": 545
},
{
"name": "blue",
"center_wavelength": 480
},
{
"name": "coastal",
"center_wavelength": 425
}
],
"platform": "worldview-02",
"instruments": [
"VNIR"
],
"associations": [],
"view:azimuth": 101.86534945454545,
"constellation": "maxar",
"off_nadir_avg": 30.756993636363635,
"off_nadir_end": 32.104233,
"off_nadir_max": 32.104233,
"off_nadir_min": 29.254648,
"rda_available": false,
"eo:cloud_cover": 0,
"scan_direction": "forward",
"view:off_nadir": 30.756993636363635,
"off_nadir_start": 29.254648,
"collect_time_end": "2022-12-29T19:46:46.737287Z",
"view:sun_azimuth": 156.91417363636364,
"raw_archive_state": "online",
"collect_time_start": "2022-12-29T19:46:36.214951Z",
"pan_resolution_avg": 0.6317207254545455,
"pan_resolution_end": 0.64994466,
"pan_resolution_max": 0.64994466,
"pan_resolution_min": 0.61310464,
"view:sun_elevation": 8.891670090909091,
"multi_resolution_avg": 2.4877443636363634,
"multi_resolution_end": 2.5032792,
"multi_resolution_max": 2.5032792,
"multi_resolution_min": 2.4703102,
"pan_resolution_start": 0.61310464,
"acquisition_rev_number": 69396,
"multi_resolution_start": 2.4703102,
"view:sun_elevation_max": 9.413769,
"view:sun_elevation_min": 8.432641,
"geolocation_uncertainty": 6.817538632598787,
"stereo_pair_identifiers": [
"c446d4a9-4bd9-483a-9eca-9c0e6f805045-inv"
],
"spacecraft_to_target_azimuth_avg": 101.86534945454545,
"spacecraft_to_target_azimuth_end": 98.66644,
"spacecraft_to_target_azimuth_max": 105.75769,
"spacecraft_to_target_azimuth_min": 98.66644,
"target_to_spacecraft_azimuth_avg": 266.66068328267346,
"target_to_spacecraft_azimuth_end": 262.9192466541697,
"target_to_spacecraft_azimuth_max": 271.19071608310963,
"target_to_spacecraft_azimuth_min": 262.9192466541697,
"spacecraft_to_target_azimuth_start": 105.75769,
"target_to_spacecraft_azimuth_start": 271.19071608310963,
"target_to_spacecraft_elevation_avg": 54.906155710776986,
"target_to_spacecraft_elevation_end": 53.32003540953537,
"target_to_spacecraft_elevation_max": 56.66845318852019,
"target_to_spacecraft_elevation_min": 53.32003540953537,
"target_to_spacecraft_elevation_start": 56.66845318852019
},
"stac_version": "1.0.0",
"stac_extensions": [
"https://stac-extensions.github.io/eo/v1.0.0/schema.json",
"https://stac-extensions.github.io/view/v1.0.0/schema.json"
]
}
],
"numberReturned": 1,
"timestamp": "2022-12-29T21:02:35.960029Z",
"links": [
{
"rel": "next",
"href": "https://api.content.maxar.com/catalog/search?collections=wv02&limit=1&page=2"
}
]
}
4c. Search results metadata¶
The search results contain the metadata for the WorldView-2 image. The "datetime": "2022-12-29T19:46:36.214951Z" indicates when it was taken and "id": "10300100E06D7600" is the Maxar Catalog's unique identifier for the image. For more details on these attributes view the Maxar Catalog's STAC Item page.
4d. Third party vendor search results metadata¶
As of June 5, 2024, the following third-party satellite imagery vendors became available to search and order: blacksky, capella, iceye, skysat, and umbra. These collections have a slightly different format of search metadata due to different vendor configurations. See the following results for this search GET request for a blacksky image:
GET
curl -X GET "https://eapi.maxar.com/e1so/search?collections=blacksky&limit=1&page=1" \
-H "Accept: application/json" \
-H "Authorization: Bearer <ADD_YOUR_ACCESS_TOKEN>"
Results
{
"type": "FeatureCollection",
"features": [
{
"id": "E00F0030010C0C00",
"bbox": [
-0.0518773429930503,
13.991741634260743,
0.0130828246888291,
14.05705276552047
],
"type": "Feature",
"links": [
{
"rel": "collection",
"href": "https://api.content.satcloud.us/catalog/collections/blacksky"
},
{
"rel": "self",
"href": "https://api.content.satcloud.us/catalog/collections/blacksky/items/E00F0030010C0C00"
},
{
"rel": "root",
"href": "https://api.content.satcloud.us/catalog/"
}
],
"assets": {},
"geometry": {
"crs": {
"type": "name",
"properties": {
"name": "EPSG:4326"
}
},
"type": "MultiPolygon",
"coordinates": [
[
[
[
-0.01470711,
14.05705277
],
[
0.01308282,
14.03475063
],
[
-0.0240555,
13.99174163
],
[
-0.05187734,
14.01413949
],
[
-0.01470711,
14.05705277
]
]
]
]
},
"collection": "blacksky",
"properties": {
"gsd": 0.9144000000000001,
"title": "05JUN24GL15010000245181278_Pan_Image_P1_P_NUMERICAL",
"datetime": "2024-06-05T15:12:35.000Z",
"eo:bands": [
{
"name": "1"
}
],
"view:azimuth": 129.65,
"eo:cloud_cover": 0,
"view:off_nadir": 20.39,
"view:sun_azimuth": 288.05,
"view:sun_elevation": 43.39
},
"stac_version": "1.0.0",
"stac_extensions": [
"https://stac-extensions.github.io/eo/v1.0.0/schema.json",
"https://stac-extensions.github.io/view/v1.0.0/schema.json"
]
}
],
"numberReturned": 1,
"timestamp": "2024-06-05T16:09:06.979703Z",
"links": [
{
"rel": "root",
"href": "https://api.content.satcloud.us/catalog/"
},
{
"rel": "next",
"href": "https://api.content.satcloud.us/catalog/search?collections=blacksky&limit=1&page=2"
}
]
}
5. Place an order¶
View the Order endpoints here: https://eapi.maxar.com/e1so/rapidoc/#post-/order
We are now going to place orders both the Maxar and blacksky images we discovered in our search, and we will have the image delivered to the bucket that was configured in step 3. To obtain the image we will use eAPI's /order REST endpoint.
We will be using cURL to conduct the orders and will need to include the token you received above as a header parameter in the request.
For detailed information on eAPI's ordering capability view the Ordering user guide.
5a. Maxar imagery - run the cURL command below (order):¶
POST
curl -X POST "https://eapi.maxar.com/e1so/order" \
-H "Accept: application/json" \
-H "Authorization: Bearer <ADD_YOUR_ACCESS_TOKEN>” \
-H "Content-Type: application/json" \
-d '{"order":{"deliveries":{"deliveryType":"S3","s3Delivery":{"bucket":"<ADD_YOUR_BUCKET_NAME>","prefix":"<ADD_YOUR_BUCKET_DELIVERY_DIRECTORY>"}},"inventoryId":"10200100D0C03400"}}'
Response
{"submissionId":"3886e613-331e-42e0-a89f-17f82e9e478a-e1so","submissionTime":"2023-01-03T17:21:57.051224"}
/order endpoint will contain a submissionId and submissionTime. The Id is a unique identifier for each order.
5b. Fulfillment of Maxar imagery order¶
The order that was submitted returned a submissionId of 3886e613-331e-42e0-a89f-17f82e9e478a-e1so. When the order is fulfilled this will be the top-level directory that is copied to the S3 bucket specified in the /order request.
5c. Delivery contents¶
Congratulations! The contents of the directory contain the 1B product you ordered.
5d. Third-party imagery - run the cURL command below (order):¶
Just as we did for Maxar image orders, we will be using cURL to conduct the order for a third-party image. You will still need to include the token you received above as a header parameter in the request.
You may notice that the cURL to order this image is exactly the same as above, just with a new inventoryId. This is because you can use the same searching and ordering endpoints, in the same format as before, now to access new third-party imagery.
For detailed information on the differences between third-party orders and regular, Maxar imagery order, please see the FAQ page.
POST
curl -X POST "https://eapi.maxar.com/e1so/order" \
-H "Accept: application/json" \
-H "Authorization: Bearer <ADD_YOUR_ACCESS_TOKEN>” \
-H "Content-Type: application/json" \
-d '{"order":{"deliveries":{"deliveryType":"S3","s3Delivery":{"bucket":"<ADD_YOUR_BUCKET_NAME>","prefix":"<ADD_YOUR_BUCKET_DELIVERY_DIRECTORY>"}},"inventoryId":"E00F0030010C0C00"}}'
Response
{"submissionId":"928b28c3-fd14-401e-9762-cbbd4e0a582b-e1so","submissionTime":"2024-06-05T16:12:33.034270954Z"}
5e. Fulfillment of third-party imagery order¶
The order that was submitted returned a submissionId of 928b28c3-fd14-401e-9762-cbbd4e0a582b-e1so. When the order is fulfilled this will be the top-level directory that is copied to the S3 bucket specified in the /order request.
5f. Delivery contents (third-party EO and SAR examples)¶
The contents of the directory above contain the third-party (blacksky) product we ordered above. You will find a NITF image file, a discovery.json file, and a license file for all EO images ordered (blacksky and skysat).
You will also notice an EOT.txt file in the bucket. This is an end-of-transmission file that will only be delivered after the rest of the order has been copied, marking the delivery as complete.
This directory contains the contents of a capella product. For SAR images like capella, iceye, and umbra, you will find a SIDD NITF file, a SICD NITF file (if available), a discovery.json file, and a license file delivered to the bucket. As with the previous example, an EOT.txt file will also be delivered at the end of order delivery.