Metadata Query Resource¶
Last updated: August 29, 2022
Queries¶
/metadata/query
List, re-run, or get the details of queries executed in an account.
Metadata Query requests¶
| http method | path | name | description |
|---|---|---|---|
| GET | /metadata/query/account/{account_id} | List the queries for an account | Retrieves a list of queries for a given account based on query parameters. |
| GET | /metadata/query/{query_id} | Get the details for a specific query | Retrieve the metadata for the given query as a GeoJSON Feature. |
| GET | /metadata/query/{query_id}/results | Re-run a query | Retrieve the latest results for the given query by re-running the query. Note, it's possible to get different results from previous executions of the query if new matching data has arrived since the previous executions. |
| DEL | /metadata/query/{query_id} | Delete a query | Delete the query record. If an order has been placed with the query ID, the query cannot be deleted. |
Headers¶
| key | value | description |
|---|---|---|
| Authorization | Bearer {{token}} | Authentication method for ARD API requests. |
| Content-Type | application/json | Applies to POST, PATCH, PUT requests, which require a JSON body. |
List the queries for an account¶
GET /metadata/query/account/{account_id}
Path parameters¶
| parameter | description | example |
|---|---|---|
| account_id | The ID of the account you are part of. |
Query parameters¶
Filter by optional query parameters.
| parameter | description | example |
|---|---|---|
| user_id | List queries executed by a specific user. | user_id=7c42cda9-dba4-4ac9-a4da-56b4123e |
| named_only | List only queries that have a query_name. |
named_only=true |
| filter | Filter results that match values contained in the given key separated by a colon. | filter=criteria.stack_depth:2 |
| limit | Limit the results returned in the list. | limit=1 |
| starting_after | The query ID after which further queries will be returned in the list, paging forward. | starting_after=Q585366936887978836 |
| ending_before | The query ID before which further queries will be returned in the list, paging backward. | ending_before=Q5853668530004169316 |
| sort | Indicates sort order, desc (default) for descending order (newest first) and asc for ascending order (oldest first) | sort=asc |
| start_date | ISO-8601 formatted, YYYY-MM-DD. The first day of the date range to filter queries on. If used without end_date, the end_date is the date of the request. | start_date=2022-02-01 |
| end_date | ISO-8601 formatted, YYYY-MM-DD. The last day of the date range to filter queries on. If used without start_date, the start_date is the date of the day of the request. | end_date=2022-02-22 |
Example using start date and end date query parameters:
https://ard.maxar.com/api/v1/metadata/query/account/5589150080369207?end_date=2022-02-22&start_date=2022-02-01
Response¶
Response fields¶
| field | description | example |
|---|---|---|
| query_id | The unique identifier assigned to the query when executed for the first time. | "query_id": "Q585874601312647606" |
| query_name | The user-provided name given to the query when exectuted for the first time. | "query_name": "ProjectYYYY" |
| account_id | The identifier for the account where the query was executed. | "account_id": "558915008036920" |
| user_id | The identifier for the user who executed the query. | "user_id": "967f33a5-1d80-4a74-9334-fcae93" |
| criteria | The criteria submitted as part of the original request. | See example below. |
| orders | The order ID for any order placed using this query ID. If no orders have been placed, the value is "null". | "orders": null |
| created | The date the query was originally executed. | "created": "2022-02-22T18:02:39Z", |
| modified | Queries cannot be modified, so the date will always be the same as the "created" date. | "modified": "2022-02-22T18:02:39Z" |
| expire_date | Queries that are not given a query_name are given an expiration date of 90 days from the day the query was executed, as long as an order has not been placed using the query ID. If a query has a query_name, the value for the expire_date will be "null". |
"expire_date": null |
| has_more | A value of "true" indicates the results extend beyond a single page. | "has_more": true |
| object | The object type is "list". | "object": "list" |
| url | The URL to the account record. Requires authentication. | "url": "https://ard.maxar.com/api/v1/metadata/query/account/55891500803692077" |
Response example¶
200 OK: success
{
"data": [
{
"query_id": "Q5862380019336611063",
"query_name": "ProjectYYYY",
"account_id": "5589150080369207736",
"user_id": "967f33a5-1d80-4a74-9334-fcae93fd203f",
"criteria": {
"stack_depth": 2,
"intersects": {
"type": "Polygon",
"coordinates": [
[
[
34.78494644165039,
-16.033192572174276
],
[
34.79443073272705,
-16.033192572174276
],
[
34.79443073272705,
-16.026428110677852
],
[
34.78494644165039,
-16.026428110677852
],
[
34.78494644165039,
-16.033192572174276
]
]
]
}
},
"orders": null,
"created": "2022-02-22T18:02:39Z",
"modified": "2022-02-22T18:02:39Z",
"expire_date": null
}
],
"has_more": true,
"object": "list",
"url": "https://ard.maxar.com/api/v1/metadata/query/account/55891500803692077"
}
Get the details of a specific query¶
/metadata/query/{query_id}
Path parameters¶
| parameter | description | example |
|---|---|---|
| query_id | The ID for the query to retrieve. |
Response¶
Shows the request used to execute the query.
200 OK: Success
404 NOT FOUND: Query ID not found
Example:
"tile_query": {
"query_id": "Q5858085789215197042",
"query_name": "ProjectZZ",
"account_id": "5589150080369207",
"user_id": "967f33a5-1d80-4a74-9334",
"criteria": {
"stack_depth": 2,
"intersects": {
"type": "Polygon",
"coordinates": [
[
[
34.78494644165039,
-16.033192572174276
],
[
34.79443073272705,
-16.033192572174276
],
[
34.79443073272705,
-16.026428110677852
],
[
34.78494644165039,
-16.026428110677852
],
[
34.78494644165039,
-16.033192572174276
]
]
]
}
},
"orders": null,
"created": "2022-02-16T19:50:47Z",
"modified": "2022-02-16T19:50:47Z",
"expire_date": null
},
"links": {
"self": "https://ard.maxar.com/api/v1/metadata/query/Q5858085789215197042"
},
"response_timestamp": "2022-02-16T19:51:39Z"
}
Re-run a query¶
GET /metadata/query/{query_id}/results
Example:
https://ard.maxar.com/api/v1/metadata/query/Q5858085789215197042/results
Path parameters¶
| parameter | description | example |
|---|---|---|
| query_id | The ID for the query to retrieve. |
Query parameters¶
Filter results by optional query parameters.
| param | description | example |
|---|---|---|
| format | Choose the tile format for the query results. Formats are "geojson" or "stac", and "order"; defaults to "geojson". | format=stac |
Response¶
200 OK: Success
404 NOT FOUND: Query ID not found
The response is the same as the response to the original query. See Tile metadata definitions for a list of properties from the response.
Delete a query¶
DEL /metadata/query/{query_id}
| parameter | description | example |
|---|---|---|
| query_id | The ID for the query to delete. |
Response codes¶
204 NO CONTENT: Success
404 NOT FOUND: Query ID not found