Maxar ARD Tile Metadata API

The Tile Metadata API provides search for ARD tiles at a lower level than the ARD Select system.

Tile metadata searches:

• return raw results
• return data immediately instead of a job ID
• do not create files such as the HTML Select viewer

For further information, see the Metadata API User Guide.

This makes searching for imagery faster and allows you to build more specific query functionality and generate your own outputs.

Metadata searches use the same parameters as Selects but do not perform the scoring to find best matches. Instead tiles are returned sorted newest to oldest. A stack_depth of 5 will return the five most recent matching tiles. If not provided, all results will be returned.

The Metadata API has some limits in processing time as well as result size, so searches that could return a large amount of data need to be broken into smaller searches. Since reaching these limits is going to depend on both the size of the query in time and space, as well as how many results have been collected within the search area, there is no rule of thumb as to how big a search is too big. Areas with frequent collection will require smaller search scopes.

For an example of limits, we'll look at a bounding box over New York City, approximately 1 degree in width, and 0.5 degrees in height. This area is frequently updated with new imagery.

• searching for all results with no query filtering will not complete within the execution time limit.
• searching for all results but restricting the search to only collections from Worldview 2 will complete but the results will be too large to return.
• searching for all results within the "fresh" image age category runs successfully. It finds roughly 760 tiles in 5 seconds.

For large searches the SDK also provides a batch search function that will efficiently divide up large area searches for you and retrieve them in parallel. Using the New York City bounding box and no filtering, it can retrieve roughly 21,000 tile records in 18 seconds.

Note that these searches still calculate and return AOI-specific metadata such as the percentage of cloud cover within your AOI's portion of the tile.

There is also functionality to search for summary metadata for tiles in a cell - instead of returning matching tiles you receive vales like tile count, earliest date, and so on.

The SDK also includes a MetaSelect object that is a drop-in replacement for Select objects. MetaSelect objects use the bulk search functionality to avoid processing limits. Like the Select objects, you can access high level tile and stack objects in the results attribute.

API Endpoint Search Functions

These functions mirror API endpoints and return similar responses.

from max_ard.metadata import search_by_area, search_by_cell_id, get_tile, get_acquisition

Searching for ARD tiles by area

The function search_by_area mirrors the functionality of creating a Select with the intersects or bbox parameter.

Default behavior returns a Python dictionary formatted as a GeoJSON FeatureCollection. By passing the parameter format="order", the function will return the tiles in the format used for the Order object's acquisitions parameter. This consists of an array of dictionaries, each describing an acquisition and its cells.

# create some search parameters, same as Selects
date_range = "2020-07-01T00:00:00Z/2021-01-25T00:00:00Z"
query = {
    "platform": {"eq": "worldview-02"},
    "aoi:cloud_free_percentage": {"gte": 51},
    "aoi:data_percentage": {"gte": 75},
}

bbox = [-74.067, 40.691, -73.883, 40.837]


tiles = search_by_area(bbox=bbox, datetime=date_range, query=query, stack_depth=3) # default format="geojson"

print(tiles['features'][0])

tiles = search_by_area(bbox=bbox, datetime=date_range, query=query, stack_depth=3, format="order")

print(tiles['acquisitions'][0])

{'type': 'Feature', 'geometry': {'type': 'Polygon', 'coordinates': [[[-73.99400042607935, 40.69151708613969], [-74.0531689427913, 40.69201754095867], [-74.05253065052106, 40.73705480495516], [-73.99332226215182, 40.73655355909112], [-73.99400042607935, 40.69151708613969]]]}, 'properties': {'cell_id': 'Z18-120002232020', 'acquisition_id': '10300100AF948600', 'constellation': 'digitalglobe', 'date': '2020-12-10', 'datetime': '2020-12-10T15:45:08Z', 'eo:cloud_cover': 13.550333925617302, 'instruments': ['VNIR'], 'modified': '2021-05-17T22:18:48Z', 'multi_resolution_avg': 2.04758922, 'multi_resolution_max': 2.0518405, 'multi_resolution_min': 2.0427806, 'off_nadir_max': 18.875525, 'off_nadir_min': 18.455303, 'pan_resolution_avg': 0.510729138, 'pan_resolution_max': 0.51177686, 'pan_resolution_min': 0.50954455, 'platform': 'worldview-02', 'tile:cloud_free_percentage': 62, 'tile:cloud_percentage': 38, 'tile:data_percentage': 100, 'tile:no_data_percentage': 0, 'tile:quadkey': '120002232020', 'tile:zone': 18, 'view:azimuth': 223.89692, 'view:off_nadir': 18.6792082, 'view:sun_azimuth': 163.75511, 'view:sun_elevation': 24.7907416, 'tile:cloud_polys': {'type': 'MultiPolygon', 'coordinates': [[[[-73.996442, 40.695605], [-73.995558, 40.695327], [-73.995754, 40.694113], [-73.997007, 40.693448], [-73.998427, 40.69346], [-73.998592, 40.694273], [-73.998229, 40.69481], [-73.996442, 40.695605]]], [[[-74.048823, 40.707535], [-74.047936, 40.707527], [-74.047231, 40.707116], [-74.047246, 40.706035], [-74.047796, 40.704824], [-74.048694, 40.704155], [-74.049759, 40.704164], [-74.050099, 40.705248], [-74.048823, 40.707535]]], [[[-74.015767, 40.697393], [-74.014524, 40.697383], [-74.014173, 40.697109], [-74.014197, 40.695488], [-74.014736, 40.695087], [-74.016866, 40.695105], [-74.017387, 40.69592], [-74.015767, 40.697393]]], [[[-74.028182, 40.698309], [-74.027117, 40.6983], [-74.026235, 40.697887], [-74.025726, 40.696261], [-74.027345, 40.694789], [-74.028767, 40.694666], [-74.029811, 40.696161], [-74.029801, 40.696836], [-74.028182, 40.698309]]], [[[-74.040218, 40.700842], [-74.039508, 40.700836], [-74.038457, 40.699881], [-74.037395, 40.699602], [-74.036882, 40.698247], [-74.035472, 40.697559], [-74.036032, 40.695672], [-74.037278, 40.695412], [-74.038712, 40.694479], [-74.039422, 40.694484], [-74.039943, 40.6953], [-74.043323, 40.694787], [-74.045085, 40.695748], [-74.045066, 40.697099], [-74.045591, 40.697644], [-74.046307, 40.697244], [-74.047727, 40.697256], [-74.048603, 40.698074], [-74.048769, 40.698886], [-74.048047, 40.699691], [-74.046982, 40.699682], [-74.046278, 40.699271], [-74.04539, 40.699263], [-74.045209, 40.699532], [-74.042903, 40.699378], [-74.042001, 40.700316], [-74.040579, 40.70044], [-74.040218, 40.700842]]], [[[-74.028058, 40.706821], [-74.027527, 40.706681], [-74.027194, 40.705192], [-74.028101, 40.703849], [-74.027752, 40.70344], [-74.026507, 40.703565], [-74.025801, 40.703289], [-74.025122, 40.701121], [-74.02531, 40.700447], [-74.027267, 40.700193], [-74.027789, 40.700873], [-74.027245, 40.701679], [-74.027596, 40.701953], [-74.029038, 40.700478], [-74.030811, 40.700628], [-74.032081, 40.698747], [-74.033502, 40.698759], [-74.034202, 40.699441], [-74.034192, 40.700116], [-74.033472, 40.700786], [-74.033802, 40.702545], [-74.033086, 40.702945], [-74.03308, 40.70335], [-74.03396, 40.703898], [-74.033767, 40.704977], [-74.031974, 40.706178], [-74.030553, 40.706166], [-74.029672, 40.705754], [-74.028058, 40.706821]]], [[[-74.052166, 40.709724], [-74.051633, 40.70972], [-74.051462, 40.709313], [-74.052172, 40.709319], [-74.052166, 40.709724]]], [[[-74.052876, 40.7127026], [-74.0528615, 40.7137267], [-74.052105, 40.714048], [-74.0519, 40.715938], [-74.051541, 40.716205], [-74.049231, 40.716321], [-74.048167, 40.716177], [-74.047114, 40.715358], [-74.047307, 40.714278], [-74.049262, 40.714159], [-74.049984, 40.713355], [-74.051933, 40.713641], [-74.052479, 40.712699], [-74.052876, 40.7127026]]], [[[-74.018346, 40.715252], [-74.018168, 40.71525], [-74.018172, 40.71498], [-74.01835, 40.714982], [-74.018346, 40.715252]]], [[[-74.024531, 40.717331], [-74.023647, 40.717054], [-74.022603, 40.715558], [-74.022789, 40.715019], [-74.023686, 40.714351], [-74.025462, 40.714366], [-74.026009, 40.713425], [-74.028851, 40.713314], [-74.029724, 40.714402], [-74.029156, 40.71683], [-74.027733, 40.716953], [-74.026851, 40.71654], [-74.025786, 40.716531], [-74.024531, 40.717331]]], [[[-74.039306, 40.714888], [-74.038063, 40.714877], [-74.037363, 40.714196], [-74.035767, 40.714047], [-74.033833, 40.71268], [-74.03402, 40.712006], [-74.036896, 40.709598], [-74.037784, 40.709605], [-74.039011, 40.710696], [-74.03917, 40.712049], [-74.038799, 40.713127], [-74.039679, 40.713675], [-74.039665, 40.71462], [-74.039306, 40.714888]]], [[[-74.031032, 40.722115], [-74.030324, 40.721974], [-74.030511, 40.7213], [-74.031397, 40.721443], [-74.031032, 40.722115]]], [[[-74.025857, 40.723829], [-74.024436, 40.723817], [-74.024448, 40.723006], [-74.025693, 40.722881], [-74.026044, 40.723154], [-74.025857, 40.723829]]], [[[-74.0487251, 40.7370235], [-74.0459165, 40.7370003], [-74.045919, 40.736833], [-74.045039, 40.736285], [-74.045044, 40.73588], [-74.045944, 40.735077], [-74.047006, 40.735356], [-74.048589, 40.73645], [-74.048759, 40.736992], [-74.0487251, 40.7370235]]], [[[-74.034937, 40.73458], [-74.033165, 40.734295], [-74.032285, 40.733747], [-74.032115, 40.733205], [-74.030696, 40.733058], [-74.029993, 40.732512], [-74.026611, 40.733024], [-74.025737, 40.73207], [-74.023256, 40.731644], [-74.023096, 40.730426], [-74.023459, 40.729889], [-74.025249, 40.728958], [-74.024898, 40.728685], [-74.022234, 40.728662], [-74.020823, 40.727975], [-74.020126, 40.727023], [-74.020138, 40.726212], [-74.021216, 40.725411], [-74.021052, 40.724464], [-74.022479, 40.72407], [-74.024772, 40.725171], [-74.026551, 40.724915], [-74.027773, 40.726412], [-74.02669, 40.727619], [-74.026682, 40.72816], [-74.027747, 40.728169], [-74.027949, 40.726549], [-74.030976, 40.726034], [-74.03081, 40.725222], [-74.029227, 40.724127], [-74.029776, 40.723051], [-74.031911, 40.722798], [-74.037759, 40.723658], [-74.038649, 40.72353], [-74.03884, 40.722586], [-74.040086, 40.722461], [-74.041319, 40.723147], [-74.041477, 40.7245], [-74.040738, 40.726521], [-74.038934, 40.728397], [-74.036971, 40.729057], [-74.037847, 40.729875], [-74.038556, 40.730016], [-74.039822, 40.728405], [-74.042323, 40.72748], [-74.042863, 40.726944], [-74.043573, 40.72695], [-74.044095, 40.727765], [-74.042658, 40.728834], [-74.041927, 40.730314], [-74.039786, 40.730972], [-74.041191, 40.732065], [-74.040643, 40.733141], [-74.038855, 40.733937], [-74.035297, 40.734313], [-74.034937, 40.73458]], [[-74.035917, 40.728237], [-74.035747, 40.727695], [-74.035392, 40.727692], [-74.035384, 40.728233], [-74.035917, 40.728237]], [[-74.03266, 40.732399], [-74.032847, 40.731725], [-74.032492, 40.731722], [-74.032482, 40.732397], [-74.03266, 40.732399]], [[-74.033066, 40.728889], [-74.033072, 40.728484], [-74.032541, 40.728344], [-74.032722, 40.728075], [-74.032012, 40.728069], [-74.03218, 40.728746], [-74.033066, 40.728889]]], [[[-74.043664, 40.733031], [-74.042957, 40.732755], [-74.042789, 40.732078], [-74.043521, 40.730598], [-74.044411, 40.73047], [-74.045822, 40.731157], [-74.046519, 40.732109], [-74.045631, 40.732101], [-74.044734, 40.73277], [-74.043664, 40.733031]]], [[[-74.029419, 40.735344], [-74.028, 40.735197], [-74.028008, 40.734657], [-74.028729, 40.733987], [-74.029439, 40.733993], [-74.03014, 40.734675], [-74.030134, 40.73508], [-74.029419, 40.735344]]], [[[-74.044062, 40.736985], [-74.0421865, 40.7369694], [-74.042193, 40.736532], [-74.042731, 40.736131], [-74.043797, 40.73614], [-74.044062, 40.736985]]], [[[-74.0065658, 40.7366683], [-73.9933223, 40.7365536], [-73.9935593, 40.7208222], [-73.993938, 40.720447], [-73.996081, 40.719655], [-73.996969, 40.719662], [-73.997673, 40.720074], [-73.999983, 40.719959], [-74.001039, 40.720644], [-74.001382, 40.721457], [-74.003507, 40.721881], [-74.004584, 40.72108], [-74.005508, 40.718655], [-74.006937, 40.718127], [-74.008356, 40.718274], [-74.009411, 40.718959], [-74.009215, 40.720174], [-74.008318, 40.720842], [-74.009014, 40.721793], [-74.009549, 40.721663], [-74.011011, 40.718838], [-74.011724, 40.718709], [-74.012586, 40.720473], [-74.01329, 40.720884], [-74.014709, 40.721031], [-74.015936, 40.722123], [-74.015918, 40.723339], [-74.014651, 40.72495], [-74.01394, 40.724943], [-74.013042, 40.725611], [-74.011973, 40.725873], [-74.011085, 40.725865], [-74.010919, 40.725053], [-74.009854, 40.725044], [-74.009315, 40.725444], [-74.009466, 40.727202], [-74.00893, 40.727468], [-74.008922, 40.728008], [-74.01052, 40.728022], [-74.010147, 40.729235], [-74.011556, 40.730058], [-74.011017, 40.730459], [-74.011174, 40.731811], [-74.009552, 40.733419], [-74.008664, 40.733411], [-74.008638, 40.735168], [-74.00649, 40.73623], [-74.0065658, 40.7366683]], [[-74.008664, 40.733411], [-74.008498, 40.732599], [-74.007606, 40.732862], [-74.007245, 40.733264], [-74.008664, 40.733411]], [[-73.997097, 40.722907], [-73.996904, 40.723986], [-73.997436, 40.723991], [-73.997975, 40.72359], [-73.997985, 40.722914], [-73.997102, 40.722636], [-73.997097, 40.722907]]], [[[-74.021638, 40.72082], [-74.019866, 40.720535], [-74.019166, 40.719853], [-74.018456, 40.719847], [-74.017376, 40.720784], [-74.016135, 40.720638], [-74.015106, 40.718197], [-74.016362, 40.717262], [-74.016368, 40.716857], [-74.015295, 40.717388], [-74.014236, 40.716974], [-74.01478, 40.716167], [-74.014437, 40.715354], [-74.013198, 40.715073], [-74.011951, 40.715332], [-74.010533, 40.715185], [-74.010577, 40.712213], [-74.010944, 40.711405], [-74.011666, 40.710601], [-74.013268, 40.710344], [-74.013643, 40.708996], [-74.012223, 40.708984], [-74.011329, 40.709382], [-74.010267, 40.709102], [-74.009743, 40.708557], [-74.007429, 40.708943], [-74.004594, 40.708513], [-74.004055, 40.708914], [-74.0035, 40.710395], [-74.002788, 40.710524], [-74.002425, 40.711062], [-74.001005, 40.711049], [-73.999239, 40.710358], [-73.997661, 40.708993], [-73.99699, 40.70642], [-73.994894, 40.704105], [-73.995081, 40.703431], [-73.99562, 40.70303], [-73.996683, 40.703174], [-73.997736, 40.703994], [-73.997724, 40.704805], [-73.998612, 40.704813], [-74.002899, 40.703093], [-74.003787, 40.703101], [-74.004481, 40.704188], [-74.007154, 40.703535], [-74.007513, 40.703268], [-74.007527, 40.702322], [-74.006129, 40.700824], [-74.006151, 40.699338], [-74.007934, 40.698812], [-74.009011, 40.698011], [-74.010076, 40.69802], [-74.011327, 40.69749], [-74.012035, 40.697631], [-74.01255, 40.698852], [-74.011824, 40.699927], [-74.010928, 40.70046], [-74.011267, 40.701544], [-74.012147, 40.702092], [-74.014628, 40.702383], [-74.015522, 40.701985], [-74.015191, 40.700361], [-74.01555, 40.700094], [-74.018039, 40.699845], [-74.019278, 40.700126], [-74.020538, 40.69892], [-74.022505, 40.697991], [-74.02287, 40.697318], [-74.023937, 40.697192], [-74.024813, 40.69801], [-74.024973, 40.699228], [-74.024432, 40.699764], [-74.022647, 40.700424], [-74.022627, 40.701775], [-74.021369, 40.702846], [-74.021363, 40.703251], [-74.021891, 40.703526], [-74.021879, 40.704337], [-74.021341, 40.704737], [-74.019745, 40.704589], [-74.018339, 40.703631], [-74.017792, 40.704572], [-74.018843, 40.705527], [-74.020094, 40.704997], [-74.020982, 40.705005], [-74.021678, 40.705956], [-74.021832, 40.707579], [-74.022185, 40.707717], [-74.023965, 40.707462], [-74.023996, 40.7053], [-74.024355, 40.705033], [-74.025063, 40.705174], [-74.026113, 40.706264], [-74.026103, 40.70694], [-74.027687, 40.707899], [-74.028384, 40.708851], [-74.029092, 40.708992], [-74.02906, 40.711154], [-74.027632, 40.711682], [-74.026731, 40.71262], [-74.023012, 40.711913], [-74.022116, 40.712446], [-74.022639, 40.713126], [-74.022272, 40.713934], [-74.021204, 40.71406], [-74.020328, 40.713242], [-74.018908, 40.71323], [-74.018719, 40.714039], [-74.017825, 40.714437], [-74.017805, 40.715788], [-74.020474, 40.715405], [-74.021696, 40.716902], [-74.021842, 40.719065], [-74.022366, 40.71961], [-74.022356, 40.720286], [-74.021638, 40.72082]], [[-74.017079, 40.716863], [-74.01726, 40.716594], [-74.017266, 40.716189], [-74.016548, 40.716723], [-74.017079, 40.716863]], [[-74.017563, 40.708083], [-74.019167, 40.707692], [-74.019173, 40.707286], [-74.016691, 40.706995], [-74.015823, 40.705636], [-74.01476, 40.705492], [-74.014002, 40.708729], [-74.015422, 40.708741], [-74.015783, 40.708339], [-74.017563, 40.708083]], [[-74.017452, 40.71565], [-74.01746, 40.715109], [-74.017282, 40.715108], [-74.017097, 40.715647], [-74.017452, 40.71565]]], [[[-74.03748, 40.718386], [-74.03642, 40.717972], [-74.035911, 40.716346], [-74.035029, 40.715933], [-74.035043, 40.714987], [-74.038227, 40.715825], [-74.03821, 40.717041], [-74.037314, 40.717574], [-74.03748, 40.718386]]], [[[-74.027366, 40.717761], [-74.027011, 40.717758], [-74.027013, 40.717622], [-74.027368, 40.717625], [-74.027366, 40.717761]]], [[[-74.0527956, 40.7183728], [-74.0527933, 40.7185353], [-74.052754, 40.718377], [-74.0527956, 40.7183728]]], [[[-74.002316, 40.718358], [-74.001253, 40.718213], [-74.001083, 40.717671], [-74.002153, 40.71741], [-74.002316, 40.718358]]], [[[-74.035168, 40.718637], [-74.03499, 40.718635], [-74.034996, 40.71823], [-74.035174, 40.718231], [-74.035168, 40.718637]]], [[[-74.033004, 40.720916], [-74.031762, 40.72077], [-74.031066, 40.719819], [-74.029116, 40.719532], [-74.028947, 40.71899], [-74.029854, 40.717646], [-74.033052, 40.717538], [-74.033579, 40.717948], [-74.034102, 40.718628], [-74.034087, 40.719709], [-74.033004, 40.720916]]]]}, 'aoi:data_area_sqkm': 26, 'aoi:data_percentage': 100, 'aoi:cloud_free_percentage': 62}}
{'id': '10300100B0831800', 'cells': ['Z18-120002221333', 'Z18-120002223111', 'Z18-120002223113', 'Z18-120002223131', 'Z18-120002223133', 'Z18-120002230222', 'Z18-120002230223', 'Z18-120002232000', 'Z18-120002232001', 'Z18-120002232002', 'Z18-120002232003', 'Z18-120002232020', 'Z18-120002232021', 'Z18-120002232022', 'Z18-120002232023']}

Searching for ARD tiles by grid cell

The function search_by_cell_id retrieves tile metadata for a given grid cell. If provided with an optional intersects or bbox geometry, it provides aoi-specific metadata for the intersection of the geometry and the cell boundary.

You can also retrieve summary data instead of matching tiles. See the summary service below.

To find cells covering an area use maxar_canvas_grid.covers(). Note that for smaller searches it is usually faster to send the area directly to the API than to break the area down to grid cells and retrieve each cell individually.

cell_id = 'Z18-120002232030'

query = {
    "platform": {"in": ["worldview-02", "worldview-03"]}
}

tiles = search_by_cell_id(cell_id, bbox=bbox, datetime=date_range, query=query, stack_depth=3)

print(tiles['features'][0])

{'type': 'Feature', 'geometry': {'type': 'Polygon', 'coordinates': [[[-73.93207410874065, 40.69096082049044], [-73.93483344076104, 40.69098631399887], [-73.93411540910382, 40.73602194799702], [-73.93202680604197, 40.73600263996322], [-73.932029, 40.734055], [-73.93207410874065, 40.69096082049044]]]}, 'properties': {'cell_id': 'Z18-120002232030', 'acquisition_id': '10300100AF948600', 'constellation': 'digitalglobe', 'date': '2020-12-10', 'datetime': '2020-12-10T15:45:08Z', 'eo:cloud_cover': 13.550333925617302, 'instruments': ['VNIR'], 'modified': '2021-05-17T22:18:45Z', 'multi_resolution_avg': 2.04758922, 'multi_resolution_max': 2.0518405, 'multi_resolution_min': 2.0427806, 'off_nadir_max': 18.875525, 'off_nadir_min': 18.455303, 'pan_resolution_avg': 0.510729138, 'pan_resolution_max': 0.51177686, 'pan_resolution_min': 0.50954455, 'platform': 'worldview-02', 'tile:cloud_free_percentage': 96, 'tile:cloud_percentage': 4, 'tile:data_percentage': 4, 'tile:no_data_percentage': 96, 'tile:quadkey': '120002232030', 'tile:zone': 18, 'view:azimuth': 223.89692, 'view:off_nadir': 18.6792082, 'view:sun_azimuth': 163.75511, 'view:sun_elevation': 24.7907416, 'tile:cloud_polys': {'type': 'MultiPolygon', 'coordinates': [[[[-73.934674, 40.7009975], [-73.9346497, 40.7025179], [-73.934374, 40.702346], [-73.934036, 40.701262], [-73.934395, 40.700995], [-73.934674, 40.7009975]]], [[[-73.9342777, 40.7258532], [-73.9342379, 40.7283473], [-73.934136, 40.728423], [-73.932719, 40.72814], [-73.932574, 40.726111], [-73.933115, 40.725576], [-73.9342777, 40.7258532]]]]}, 'aoi:data_area_sqkm': 2, 'aoi:data_percentage': 10, 'aoi:cloud_free_percentage': 5}}

Retrieving metadata for an acquisition

To retrieve metadata for an acquisition, use metadata.get_acquisition with the acquisition ID. Like the above search functions, the ARD tiles can be returned in several formats.

tiles = get_acquisition('10300100AF948600')
print(tiles['features'][0])

{'type': 'Feature', 'geometry': {'type': 'Polygon', 'coordinates': [[[-73.99332226215182, 40.73655355909112], [-74.05253065052106, 40.73705480495516], [-74.05189091316382, 40.78209170810315], [-73.99264256290057, 40.78158967013944], [-73.99332226215182, 40.73655355909112]]]}, 'properties': {'cell_id': 'Z18-120002232002', 'acquisition_id': '10300100AF948600', 'constellation': 'digitalglobe', 'date': '2020-12-10', 'datetime': '2020-12-10T15:45:08Z', 'eo:cloud_cover': 13.550333925617302, 'instruments': ['VNIR'], 'modified': '2021-05-17T22:18:47Z', 'multi_resolution_avg': 2.04758922, 'multi_resolution_max': 2.0518405, 'multi_resolution_min': 2.0427806, 'off_nadir_max': 18.875525, 'off_nadir_min': 18.455303, 'pan_resolution_avg': 0.510729138, 'pan_resolution_max': 0.51177686, 'pan_resolution_min': 0.50954455, 'platform': 'worldview-02', 'tile:cloud_free_percentage': 78, 'tile:cloud_percentage': 22, 'tile:data_percentage': 100, 'tile:no_data_percentage': 0, 'tile:quadkey': '120002232002', 'tile:zone': 18, 'view:azimuth': 223.89692, 'view:off_nadir': 18.6792082, 'view:sun_azimuth': 163.75511, 'view:sun_elevation': 24.7907416, 'tile:cloud_polys': {'type': 'MultiPolygon', 'coordinates': [[[[-74.0522263, 40.7584961], [-74.0520878, 40.7682421], [-74.048494, 40.768069], [-74.046726, 40.767378], [-74.046209, 40.766293], [-74.045154, 40.765474], [-74.04499, 40.764526], [-74.043931, 40.763977], [-74.044127, 40.762763], [-74.045027, 40.761959], [-74.04505, 40.760338], [-74.045774, 40.759398], [-74.046309, 40.759267], [-74.047901, 40.759821], [-74.050228, 40.758624], [-74.0522263, 40.7584961]]], [[[-73.996616, 40.754927], [-73.996083, 40.754923], [-73.996269, 40.754384], [-73.996622, 40.754522], [-73.996616, 40.754927]]], [[[-73.997344, 40.765609], [-73.996638, 40.765332], [-73.996468, 40.76479], [-73.995584, 40.764512], [-73.995788, 40.762758], [-73.99685, 40.763037], [-73.996474, 40.764385], [-73.997357, 40.764798], [-73.997344, 40.765609]]], [[[-73.99915, 40.763733], [-73.998263, 40.76359], [-73.998271, 40.763049], [-73.999515, 40.76306], [-73.99915, 40.763733]]], [[[-74.004069, 40.767559], [-74.00336, 40.767417], [-74.002835, 40.766872], [-74.001052, 40.767262], [-73.999103, 40.76684], [-73.998225, 40.766157], [-73.998251, 40.7644], [-74.000927, 40.763748], [-74.002879, 40.7639], [-74.003225, 40.764579], [-74.002685, 40.764979], [-74.002675, 40.765655], [-74.003215, 40.765254], [-74.00446, 40.76513], [-74.005167, 40.765406], [-74.004604, 40.767428], [-74.004069, 40.767559]]], [[[-74.011046, 40.740458], [-74.010699, 40.739915], [-74.011412, 40.739786], [-74.011583, 40.740193], [-74.011046, 40.740458]]], [[[-74.037194, 40.750544], [-74.036484, 40.750538], [-74.036491, 40.749997], [-74.03703, 40.749596], [-74.037559, 40.749871], [-74.037194, 40.750544]]], [[[-74.0459165, 40.7370003], [-74.0487251, 40.7370235], [-74.048039, 40.737661], [-74.045911, 40.737374], [-74.0459165, 40.7370003]]], [[[-74.0421865, 40.7369694], [-74.044062, 40.736985], [-74.044137, 40.737224], [-74.045201, 40.737368], [-74.045718, 40.738453], [-74.046958, 40.738734], [-74.047305, 40.739277], [-74.047114, 40.740221], [-74.045676, 40.741425], [-74.044257, 40.741279], [-74.043003, 40.741944], [-74.041233, 40.741524], [-74.040514, 40.742058], [-74.040314, 40.743678], [-74.038715, 40.743665], [-74.037639, 40.744332], [-74.036929, 40.744326], [-74.036228, 40.743644], [-74.036792, 40.741487], [-74.038945, 40.740018], [-74.039854, 40.73854], [-74.042175, 40.737748], [-74.0421865, 40.7369694]]], [[[-73.9930749, 40.7529571], [-73.9933223, 40.7365536], [-74.0065658, 40.7366683], [-74.006654, 40.737178], [-74.007185, 40.737317], [-74.008232, 40.738542], [-74.008216, 40.739623], [-74.007845, 40.740701], [-74.00624, 40.741093], [-74.005697, 40.741764], [-74.006376, 40.743931], [-74.005637, 40.745817], [-74.005096, 40.746353], [-74.002421, 40.747005], [-74.001515, 40.748214], [-74.001684, 40.748756], [-74.002914, 40.749712], [-74.003624, 40.749718], [-74.00506, 40.748785], [-74.006126, 40.748794], [-74.00682, 40.749881], [-74.008233, 40.750434], [-74.008401, 40.751111], [-74.009283, 40.751524], [-74.010503, 40.753156], [-74.010637, 40.756129], [-74.011341, 40.756541], [-74.013469, 40.756829], [-74.013986, 40.757915], [-74.013785, 40.759535], [-74.015023, 40.759951], [-74.015723, 40.760632], [-74.014092, 40.76278], [-74.011427, 40.762757], [-74.011259, 40.76208], [-74.012349, 40.760468], [-74.01058, 40.759913], [-74.010029, 40.761124], [-74.009492, 40.76139], [-74.009482, 40.762065], [-74.007148, 40.763667], [-74.006615, 40.763662], [-74.00609, 40.763117], [-74.00628, 40.762308], [-74.007178, 40.76164], [-74.006486, 40.760418], [-74.005234, 40.760948], [-74.002033, 40.761055], [-74.000961, 40.761451], [-73.999907, 40.760631], [-73.997779, 40.760343], [-73.997078, 40.759661], [-73.996745, 40.758172], [-73.993923, 40.756796], [-73.993939, 40.755715], [-73.995013, 40.755184], [-73.99572, 40.75546], [-73.995889, 40.756002], [-73.997658, 40.756558], [-74.000864, 40.756045], [-74.001403, 40.755645], [-74.001238, 40.754832], [-74.000362, 40.754014], [-74.000554, 40.75307], [-73.999675, 40.752387], [-73.999332, 40.751573], [-73.997018, 40.751823], [-73.995959, 40.751408], [-73.994713, 40.751533], [-73.994697, 40.752614], [-73.995934, 40.75303], [-73.996635, 40.753711], [-73.996629, 40.754117], [-73.995025, 40.754373], [-73.994145, 40.753825], [-73.994337, 40.752881], [-73.9930749, 40.7529571]], [[-73.993827, 40.75139], [-73.993831, 40.75112], [-73.993298, 40.751115], [-73.993471, 40.751387], [-73.993827, 40.75139]], [[-73.997477, 40.744936], [-73.996971, 40.743175], [-73.995729, 40.743029], [-73.995029, 40.742347], [-73.994139, 40.742474], [-73.994304, 40.743286], [-73.995529, 40.744513], [-73.997477, 40.744936]], [[-74.006614, 40.751771], [-74.006626, 40.75096], [-74.006103, 40.75028], [-74.003792, 40.750395], [-74.004135, 40.751209], [-74.005015, 40.751757], [-74.006614, 40.751771]]], [[[-73.9927881, 40.7719564], [-73.9927908, 40.7717761], [-73.992808, 40.771785], [-73.9927881, 40.7719564]]], [[[-74.008607, 40.773138], [-74.008251, 40.773135], [-74.008255, 40.772865], [-74.008611, 40.772868], [-74.008607, 40.773138]]], [[[-74.048156, 40.779281], [-74.047092, 40.779137], [-74.046041, 40.778048], [-74.04515, 40.778176], [-74.044429, 40.778845], [-74.041937, 40.779095], [-74.041408, 40.77882], [-74.041246, 40.777738], [-74.043052, 40.775726], [-74.044298, 40.775601], [-74.045532, 40.776287], [-74.046267, 40.774671], [-74.047345, 40.77387], [-74.048233, 40.773877], [-74.049112, 40.77456], [-74.049452, 40.775644], [-74.050159, 40.77592], [-74.050501, 40.776868], [-74.049586, 40.778753], [-74.048156, 40.779281]]], [[[-73.9926914, 40.7783557], [-73.9927089, 40.7771955], [-73.993084, 40.777057], [-73.993607, 40.777738], [-73.992886, 40.778407], [-73.9926914, 40.7783557]]], [[[-74.0266259, 40.7818813], [-74.0110671, 40.781749], [-74.009734, 40.780985], [-74.00993, 40.77977], [-74.010651, 40.779101], [-74.012788, 40.778849], [-74.01667, 40.780774], [-74.017383, 40.780645], [-74.018641, 40.77971], [-74.021485, 40.779734], [-74.023255, 40.780289], [-74.024499, 40.7803], [-74.026087, 40.781124], [-74.0266259, 40.7818813]]], [[[-74.049197, 40.781047], [-74.048311, 40.780904], [-74.048318, 40.780364], [-74.049203, 40.780641], [-74.049197, 40.781047]]], [[[-73.9939887, 40.7816014], [-73.9926426, 40.7815897], [-73.992653, 40.7809018], [-73.993209, 40.780572], [-73.994269, 40.780986], [-73.9939887, 40.7816014]]], [[[-73.999848, 40.776441], [-73.999315, 40.776436], [-73.999498, 40.776032], [-73.999852, 40.77617], [-73.999848, 40.776441]]], [[[-74.004784, 40.779186], [-74.004253, 40.779046], [-74.004263, 40.77837], [-74.003738, 40.777825], [-74.00197, 40.777135], [-74.001278, 40.775912], [-74.001659, 40.774159], [-74.003269, 40.773497], [-74.004156, 40.77364], [-74.004485, 40.7754], [-74.005725, 40.775681], [-74.006771, 40.777041], [-74.004784, 40.779186]]], [[[-74.010035, 40.772745], [-74.008793, 40.772599], [-74.008621, 40.772192], [-74.006666, 40.772175], [-74.005963, 40.771629], [-74.003467, 40.772148], [-74.002413, 40.771328], [-74.002245, 40.770651], [-74.002607, 40.770249], [-74.004028, 40.770261], [-74.004041, 40.76945], [-74.005117, 40.768784], [-74.005133, 40.767703], [-74.005492, 40.767436], [-74.007617, 40.767995], [-74.007475, 40.765561], [-74.008029, 40.764215], [-74.009642, 40.763283], [-74.010886, 40.763293], [-74.011942, 40.763978], [-74.011205, 40.765728], [-74.011898, 40.76695], [-74.012966, 40.766824], [-74.012956, 40.7675], [-74.011892, 40.767356], [-74.010991, 40.768159], [-74.009566, 40.768417], [-74.009558, 40.768957], [-74.010796, 40.769373], [-74.012193, 40.771007], [-74.012006, 40.771681], [-74.010035, 40.772745]]]]}, 'aoi:data_area_sqkm': 26, 'aoi:data_percentage': 100, 'aoi:cloud_free_percentage': 80}}

Retrieving metadata for a specific ARD tile

To retrieve metadata for a specific ARD tile, use metadata.get_tile with the cell ID and the acquisition ID. This will return the tile metadata as a GeoJSON Feature.

tile = get_tile(cell_id='Z18-120002232030', acq_id='10300100AF948600')
print(tile)

{'type': 'Feature', 'geometry': {'type': 'Polygon', 'coordinates': [[[-73.93207410874065, 40.69096082049044], [-73.93483344076104, 40.69098631399887], [-73.93411540910382, 40.73602194799702], [-73.93202680604197, 40.73600263996322], [-73.932029, 40.734055], [-73.93207410874065, 40.69096082049044]]]}, 'properties': {'cell_id': 'Z18-120002232030', 'acquisition_id': '10300100AF948600', 'constellation': 'digitalglobe', 'date': '2020-12-10', 'datetime': '2020-12-10T15:45:08Z', 'eo:cloud_cover': 13.550333925617302, 'instruments': ['VNIR'], 'modified': '2021-05-17T22:18:45Z', 'multi_resolution_avg': 2.04758922, 'multi_resolution_max': 2.0518405, 'multi_resolution_min': 2.0427806, 'off_nadir_max': 18.875525, 'off_nadir_min': 18.455303, 'pan_resolution_avg': 0.510729138, 'pan_resolution_max': 0.51177686, 'pan_resolution_min': 0.50954455, 'platform': 'worldview-02', 'tile:cloud_free_percentage': 96, 'tile:cloud_percentage': 4, 'tile:data_percentage': 4, 'tile:no_data_percentage': 96, 'tile:quadkey': '120002232030', 'tile:zone': 18, 'view:azimuth': 223.89692, 'view:off_nadir': 18.6792082, 'view:sun_azimuth': 163.75511, 'view:sun_elevation': 24.7907416, 'tile:cloud_polys': {'type': 'MultiPolygon', 'coordinates': [[[[-73.934674, 40.7009975], [-73.9346497, 40.7025179], [-73.934374, 40.702346], [-73.934036, 40.701262], [-73.934395, 40.700995], [-73.934674, 40.7009975]]], [[[-73.9342777, 40.7258532], [-73.9342379, 40.7283473], [-73.934136, 40.728423], [-73.932719, 40.72814], [-73.932574, 40.726111], [-73.933115, 40.725576], [-73.9342777, 40.7258532]]]]}}}

Summary Metadata

from max_ard.metadata import summarize_cell, summarize_area, register_summary_area

The ARD data catalog also keeps summary metadata for data cells over limited areas. If an area is not currently covered, you can submit areas you would like us to track.

metadata.summarize_cell returns a GeoJSON Feature for a given cell. The feature properties show summary metadata for that cell. If the cell is not indexed a MissingSummary exception is raised.

print(summarize_cell("Z13-031133320213")['properties'])

{'cell_id': 'Z13-031133320213', 'tile_count': 117, 'min_date': '2010-06-24', 'min_date_timestamp': 1277337600, 'max_date': '2022-01-26', 'max_date_timestamp': 1643220089, 'platforms': {'geoeye-01': 41, 'worldview-01': 9, 'worldview-02': 46, 'worldview-03': 17, 'worldview-04': 4}, 'data_percentage_90': 55, 'data_percentage_75': 58, 'data_percentage_50': 64, 'data_percentage_25': 66, 'cloud_free_percentage_90': 73, 'cloud_free_percentage_75': 76, 'cloud_free_percentage_50': 79, 'cloud_free_percentage_25': 84, 'created': '2022-01-31T13:25:11Z', 'modified': '2022-02-27T06:28:36Z'}

metadata.summarize_area returns a GeoJSON FeatureCollection of cells covering a given area. Default behavior is to return all cells within the area that are currently tracked by the summary system. If the area includes untracked cells, they are skipped. To raise an error that there are untracked cells within the search area, pass the keyword strict=True. This will cause the function to raise a MissingSummary exception. You can then register your area using register_summary_area to start indexing all cells in your area.

metadata.register_summary_area allows you to add an area to have summary data calculated. After adding an area using intersects or bbox parameters, any unwatched cells are queued up to calculate statistics and the summary should be available momentarily. Summary data is updated whenever new collections occur.

register_summary_area(bbox=[-106.8, 35.1, -106.4, 35.4])

bbox = [-106.8, 35.1, -106.4, 35.4]
summaries = summarize_area(bbox=bbox)['features']
print(len(summaries), 'cells')
print(summaries[0]['properties'])

56 cells
{'cell_id': 'Z13-031133320203', 'tile_count': 84, 'min_date': '2011-05-22', 'min_date_timestamp': 1306022400, 'max_date': '2022-01-23', 'max_date_timestamp': 1642960388, 'platforms': {'geoeye-01': 29, 'worldview-01': 6, 'worldview-02': 34, 'worldview-03': 14, 'worldview-04': 1}, 'data_percentage_90': 20, 'data_percentage_75': 23, 'data_percentage_50': 32, 'data_percentage_25': 48, 'cloud_free_percentage_90': 52, 'cloud_free_percentage_75': 54, 'cloud_free_percentage_50': 55, 'cloud_free_percentage_25': 56, 'created': '2022-01-31T13:25:16Z', 'modified': '2022-02-26T07:53:31Z'}

Advanced Search

Batch search for large areas

from max_ard.metadata import batch_search_by_area

Some searches can be large enough to cause the metadata service to error or time out. If you encounter these limits, we recommend you break the search up by cells, or to shorter date ranges. Breaking up a larger search area to smaller sub-areas can return confusing results.

The SDK includes a basic batched search function: batch_search_by_area. This function works efficiently over large areas by:

• the search area is broken down to individual tiles
• the tiles are searched asynchronously in 8 parallel threads
• you can also provide custom filter functions that run on each batch in the asynchronous process

Filter functions should take the GeoJSON-like tile input, and return True if the tile meets the filter requirements. You do not have to use the filter functions, but there can be some speed up by applying this processing to the batches.

For example, these two filter functions will keep tiles that were captured on a Tuesday by any Worldview satellite:

from datetime import datetime

def match_worldview(tile):
    # check if the word "world" is in the platform name
    return "world" in tile["properties"]["platform"].lower()


def tuesdays(tile):
    # check if the date is a Tuesday
    date = tile["properties"].get("date")
    return datetime.strptime(date, "%Y-%m-%d").weekday() == 3

To have these filters applied, pass them in a list. A tile must pass all filters to be returned (they are logically ANDed). Filters execute in order, so more expensive filters can be placed later in the list.

tiles = batch_search_by_area(bbox=bbox, filters=[match_worldview, tuesdays])

print(tiles['features'][0])

{'type': 'Feature', 'geometry': {'type': 'Polygon', 'coordinates': [[[-106.761168016614, 35.36549648670249], [-106.8161802274594, 35.36468200254137], [-106.8171909407376, 35.40974359423751], [-106.762148154538, 35.41055942822295], [-106.761168016614, 35.36549648670249]]]}, 'properties': {'cell_id': 'Z13-031133231111', 'acquisition_id': '104001004E3A9900', 'constellation': 'digitalglobe', 'date': '2019-06-20', 'datetime': '2019-06-20T18:07:43Z', 'eo:cloud_cover': 0, 'instruments': ['VNIR'], 'modified': None, 'multi_resolution_avg': 1.3752407111111111, 'multi_resolution_max': 1.4526455, 'multi_resolution_min': 1.3372802, 'off_nadir_max': 24.132902, 'off_nadir_min': 16.947643, 'pan_resolution_avg': 0.3436424311111111, 'pan_resolution_max': 0.36278623, 'pan_resolution_min': 0.33434078, 'platform': 'worldview-03', 'tile:cloud_free_percentage': None, 'tile:cloud_percentage': None, 'tile:data_percentage': None, 'tile:no_data_percentage': None, 'tile:quadkey': None, 'tile:zone': None, 'view:azimuth': 252.0356911111111, 'view:off_nadir': 19.512473222222223, 'view:sun_azimuth': 127.3408788888889, 'view:sun_elevation': 72.41449733333333, 'tile:cloud_polys': None, 'aoi:data_area_sqkm': 14, 'aoi:data_percentage': 100, 'aoi:cloud_free_percentage': 100}}

Using MetaSelect objects as a lighter Select

from max_ard.metadata import MetaSelect

The MetaSelect object works like a standard Select object but uses the SDK's bulk select functionality to retrieve results faster. Since MetaSelects break up the search work and do not generate output files, they generally will generate results over large areas that can cause a regular Select to fail.

There are a few differences in how MetaSelects work:

• Default stack depth is unlimited, use stack_depth to set a limit on tiles returned.
• There is no scoring on parameters, so if results are limited by passing a stack depth, tiles are returned sorted newest to oldest.
• The search is run when the object is initialized. You do not need to call submit() or wait_for_success(), however for compatibility both methods can be called without raising errors. The same applies to properties like succeeded - they are set to the appropriate values for compatibility but if the object successfully initializes, it has already completed the search process.
• No file artifacts are generated, so methods like get_file_links() will raise NotImplemented exceptions if called.

MetaSelects expose the same results property that returns a fully-featured SelectResults object.

# tiles = search_by_area(bbox=bbox, datetime=date_range, query=query, stack_depth=3)

select = MetaSelect(bbox=bbox, datetime=date_range, query=query, stack_depth=3)

print('Select finished:', select.finished)

print(select.results)

Select finished: True
<SelectResult (105 tiles in 6 acquisitions) >

Persisting Searches

The Metadata API saves searches much like how Selects are saved. This is primarily used for the ARD user interface and this functionality is not currently exposed in the SDK.