# Standard Images API

## Collections

The `collections` endpoint returns all imagery datasets accessible through your account. This endpoint serves as the discovery mechanism for available imagery and must be called before querying specific images. Usually, you'll have access to only one or two collections that cover the full extent of the geographic area available to your account.

### Common Use Cases

* **Application initialization** - retrieve and cache available collections
* **Geographic discovery** - identify which collections cover your areas of interest
* **Permission validation** - confirm access to specific datasets before building user interfaces

### Response Highlights

Each collection in the response includes:

* **`id`** - unique identifier required for all subsequent image queries
* **`extent`** - geographic boundaries for the collection
* **`title` and `description`** - human-readable metadata for user interfaces
* **`links`** - includes the items endpoint URL for querying images within this collection

### Implementation Notes

💡 **Cache collections data** - this endpoint returns relatively static information that changes infrequently. Cache the response to avoid unnecessary API calls. Collection IDs are stable over time, so once you have it saved, you may not need to revisit this endpoint.

💡 **Check extent data** - use the spatial extent information to verify the collection's region aligns with your project location.

## Retrieve a list of all collections

> Access and browse available feature collections accessible to the authenticated user.

```json
{"openapi":"3.1.0","info":{"title":"Spexi API","version":"1.0"},"servers":[{"url":"https://world.spexi.com","description":"API URL"}],"security":[{"bearer-token":[]}],"components":{"securitySchemes":{"bearer-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","name":"Authorization","description":"Enter your Bearer token","in":"header"}},"schemas":{"CollectionsListResponse":{"type":"object","properties":{"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string","description":"Supplies the URI to a remote resource (or resource fragment)."},"rel":{"description":"The type or semantics of the relation.","type":"string","enum":["alternate","https://www.opengis.net/def/rel/ogc/1.0/data-meta","https://www.opengis.net/def/rel/ogc/1.0/conformance","https://www.opengis.net/def/rel/ogc/1.0/tiling-schemes","https://www.opengis.net/def/rel/ogc/1.0/tiling-scheme","https://www.opengis.net/def/rel/ogc/1.0/tilesets-vector","describedby","license","self","item","items","next","service-desc","service-doc","service-meta","https://www.opengis.net/def/ogc/image","https://www.spexi.com/def/image/oriented","https://www.spexi.com/def/image/panorama"]},"type":{"type":"string","enum":["application/json","application/geo+json","text/html","application/openapi+json;version=3.0","application/vnd.mapbox-vector-tile","application/vnd.mapbox.tile+json"],"description":"A hint indicating what the media type of the result of dereferencing the link should be."},"templated":{"type":"boolean","description":"This flag set to true if the link is a URL template."},"varBase":{"type":"string","description":"A base path to retrieve semantic information about the variables used in URL template."},"hreflang":{"type":"string","description":"A hint indicating what the language of the result of dereferencing the link should be."},"title":{"type":"string","description":"Used to label the destination of a link such that it can be used as a human-readable identifier."},"length":{"type":"number"}},"required":["href","rel"]}},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string","description":"Supplies the URI to a remote resource (or resource fragment)."},"rel":{"description":"The type or semantics of the relation.","type":"string","enum":["alternate","https://www.opengis.net/def/rel/ogc/1.0/data-meta","https://www.opengis.net/def/rel/ogc/1.0/conformance","https://www.opengis.net/def/rel/ogc/1.0/tiling-schemes","https://www.opengis.net/def/rel/ogc/1.0/tiling-scheme","https://www.opengis.net/def/rel/ogc/1.0/tilesets-vector","describedby","license","self","item","items","next","service-desc","service-doc","service-meta","https://www.opengis.net/def/ogc/image","https://www.spexi.com/def/image/oriented","https://www.spexi.com/def/image/panorama"]},"type":{"type":"string","enum":["application/json","application/geo+json","text/html","application/openapi+json;version=3.0","application/vnd.mapbox-vector-tile","application/vnd.mapbox.tile+json"],"description":"A hint indicating what the media type of the result of dereferencing the link should be."},"templated":{"type":"boolean","description":"This flag set to true if the link is a URL template."},"varBase":{"type":"string","description":"A base path to retrieve semantic information about the variables used in URL template."},"hreflang":{"type":"string","description":"A hint indicating what the language of the result of dereferencing the link should be."},"title":{"type":"string","description":"Used to label the destination of a link such that it can be used as a human-readable identifier."},"length":{"type":"number"}},"required":["href","rel"]}},"extent":{"type":"object","properties":{"spatial":{"type":"object","properties":{"bbox":{"type":"array","items":{},"minItems":1},"crs":{"type":"string","enum":["https://www.opengis.net/def/crs/OGC/1.3/CRS84"]}},"required":["bbox","crs"]},"temporal":{"type":"object","properties":{"interval":{"type":"array","items":{"type":"array","items":{"type":"string","format":"date-time","nullable":true},"minItems":2,"maxItems":2},"minItems":1},"trs":{"type":"string","enum":["https://www.opengis.net/def/uom/ISO-8601/0/Gregorian"]}},"required":["interval","trs"]}},"required":["spatial","temporal"]},"crs":{"type":"array","items":{"type":"string"}},"storageCrs":{"type":"string","format":"uri"}},"required":["id","name","title","description","links","extent","crs","storageCrs"]}}},"required":["links","collections"]},"ErrorDto":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem"},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem"}},"required":["type"],"title":"Exception Schema","description":"JSON schema for exceptions based on RFC 7807"}}},"paths":{"/api/ogc/v1/collections":{"get":{"description":"Access and browse available feature collections accessible to the authenticated user.","operationId":"CollectionsController_getCollections","parameters":[{"name":"f","required":false,"in":"path","description":"Response format type","schema":{"enum":["application/json","text/html"],"type":"string"}},{"name":"Accept","in":"header","description":"Response format (unless specified by the `f` parameter)","required":false,"schema":{"type":"string","enum":["application/json","text/html","*/*"]}},{"name":"Authorization","in":"header","description":"Bearer token for authenticated requests","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized"},"406":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Retrieve a list of all collections","tags":["OGC API"]}}}}
```

## Items

The items endpoint retrieves imagery from a specific collection. This endpoint supports extensive filtering capabilities to find precisely the images you need based on location, camera parameters, and capture attributes.

### Common Use Cases

* **Location-based queries** - find all images containing a specific point or area
* **Camera angle filtering** - retrieve images captured at specific pitch or heading angles
* **Temporal searches** - get images captured within date ranges
* **Quality filtering** - use focused parameter to get the best images for your area of interest
* **Systematic processing** - iterate through large datasets with pagination

### Key Parameters

While this endpoint supports many parameters, these handle the majority of use cases:

**Spatial Filtering:**

* **`p`** - find images containing a specific point (with optional buffer radius)
* **`bbox`** - retrieve images within a rectangular geographic area

**Smart Filtering:**

* **`focused`** - apply intelligent filtering to get the most relevant images
  * Use `focused=focused` for most practical applications
  * Use `focused=5-view` when you need multiple perspectives of the same location

**Camera Parameters:**

* **`pitch`** - filter by camera angle (-90° for straight down, -60° for oblique views)
* **`heading`** - filter by compass direction the camera was facing
* **`altitude`** - filter by flight height above ground level
* **`captured_at`** - filter by image capture date

### Response Highlights

Each image feature includes:

* **`geometry`** - precise geographic footprint showing the area captured in the image
* **`properties`** - comprehensive metadata including flight parameters and capture information
* **`links`** - download URLs for the actual image file (look for `"title": "Raw Image"`)

### Implementation Notes

💡 **Always use focused filtering** - unless you specifically need all overlapping images, add `&focused=focused` to all queries. This dramatically improves response relevance and reduces processing overhead.

💡 **Extract download URLs from links** - to download the actual image file, iterate through the `links` array in each feature and find the object with `"title": "Raw Image"` and `"type": "image/jpeg"`. The `href` field contains the direct download URL.

💡 **Handle pagination** - large queries return paginated results. Check for `"rel": "next"` links in the response and follow them to retrieve complete datasets.

💡 **Combine parameters wisely** - all filter parameters use AND logic. For example, `?pitch=-90&heading=0&focused=focused` returns only nadir images facing north that prominently feature your query area.

## Retrieve image features from a collection

> Discover and download high-quality drone imagery based on geographic location and camera parameters. This endpoint allows you to find precise aerial views of specific points or regions of interest, with filters for camera orientation, angle, and coverage area.

```json
{"openapi":"3.1.0","info":{"title":"Spexi API","version":"1.0"},"servers":[{"url":"https://world.spexi.com","description":"API URL"}],"security":[{"bearer-token":[]}],"components":{"securitySchemes":{"bearer-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","name":"Authorization","description":"Enter your Bearer token","in":"header"}},"schemas":{"OrientedImageCollectionItemsResponse":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["Feature"]},"geometry":{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{}}}},"required":["type","coordinates"],"description":"Geographic area captured within the image."},"properties":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of the image."},"pitch":{"type":"number","description":"Camera angle below horizontal in degrees. Range: [-135, 45], where -90 is directly downward (nadir), -60 is oblique, and -30 is more horizontal."},"roll":{"type":"number","description":"Camera roll angle in degrees."},"altitude":{"type":"number","description":"Altitude of the camera above ground level in meters."},"heading":{"type":"number","description":"Camera heading in degrees. Range: [0, 360), where 0 is North, 90 is East, etc."},"cameraPosition":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{}},"required":["type","coordinates"],"description":"Point location of the camera at time of capture."},"distance":{"type":"number","description":"Distance from the query point to the camera position in meters."},"capturedAt":{"type":"string","format":"date-time","description":"Timestamp when the image was captured."},"captureType":{"type":"string","description":"Type of image capture: 'panorama', 'oblique', or 'orthomosaic'."}},"required":["id","pitch","roll","altitude","heading","cameraPosition","capturedAt","captureType"]},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string","description":"Supplies the URI to a remote resource (or resource fragment)."},"rel":{"description":"The type or semantics of the relation.","type":"string","enum":["alternate","https://www.opengis.net/def/rel/ogc/1.0/data-meta","https://www.opengis.net/def/rel/ogc/1.0/conformance","https://www.opengis.net/def/rel/ogc/1.0/tiling-schemes","https://www.opengis.net/def/rel/ogc/1.0/tiling-scheme","https://www.opengis.net/def/rel/ogc/1.0/tilesets-vector","describedby","license","self","item","items","next","service-desc","service-doc","service-meta","https://www.opengis.net/def/ogc/image","https://www.spexi.com/def/image/oriented","https://www.spexi.com/def/image/panorama"]},"type":{"type":"string","enum":["application/json","application/geo+json","text/html","application/openapi+json;version=3.0","application/vnd.mapbox-vector-tile","application/vnd.mapbox.tile+json"],"description":"A hint indicating what the media type of the result of dereferencing the link should be."},"templated":{"type":"boolean","description":"This flag set to true if the link is a URL template."},"varBase":{"type":"string","description":"A base path to retrieve semantic information about the variables used in URL template."},"hreflang":{"type":"string","description":"A hint indicating what the language of the result of dereferencing the link should be."},"title":{"type":"string","description":"Used to label the destination of a link such that it can be used as a human-readable identifier."},"length":{"type":"number"}},"required":["href","rel"]}}},"required":["id","type","geometry","properties","links"]}},"numberReturned":{"type":"number","description":"The number of features in the response."},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string","description":"Supplies the URI to a remote resource (or resource fragment)."},"rel":{"description":"The type or semantics of the relation.","type":"string","enum":["alternate","https://www.opengis.net/def/rel/ogc/1.0/data-meta","https://www.opengis.net/def/rel/ogc/1.0/conformance","https://www.opengis.net/def/rel/ogc/1.0/tiling-schemes","https://www.opengis.net/def/rel/ogc/1.0/tiling-scheme","https://www.opengis.net/def/rel/ogc/1.0/tilesets-vector","describedby","license","self","item","items","next","service-desc","service-doc","service-meta","https://www.opengis.net/def/ogc/image","https://www.spexi.com/def/image/oriented","https://www.spexi.com/def/image/panorama"]},"type":{"type":"string","enum":["application/json","application/geo+json","text/html","application/openapi+json;version=3.0","application/vnd.mapbox-vector-tile","application/vnd.mapbox.tile+json"],"description":"A hint indicating what the media type of the result of dereferencing the link should be."},"templated":{"type":"boolean","description":"This flag set to true if the link is a URL template."},"varBase":{"type":"string","description":"A base path to retrieve semantic information about the variables used in URL template."},"hreflang":{"type":"string","description":"A hint indicating what the language of the result of dereferencing the link should be."},"title":{"type":"string","description":"Used to label the destination of a link such that it can be used as a human-readable identifier."},"length":{"type":"number"}},"required":["href","rel"]}}},"required":["id","title","type","features","numberReturned","links"]},"ErrorDto":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this occurrence of the problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem"},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem"}},"required":["type"],"title":"Exception Schema","description":"JSON schema for exceptions based on RFC 7807"}}},"paths":{"/api/ogc/v1/collections/{collectionId}+standard-images/items":{"get":{"description":"Discover and download high-quality drone imagery based on geographic location and camera parameters. This endpoint allows you to find precise aerial views of specific points or regions of interest, with filters for camera orientation, angle, and coverage area.","operationId":"OrientedImageCollectionController_getFeatures","parameters":[{"name":"collectionId","required":true,"in":"path","description":"Collection identifier, discoverable from the `/api/ogc/v1/collections` endpoint","schema":{"pattern":"^[a-z0-9]+$","type":"string"}},{"name":"bbox","required":false,"in":"query","description":"An area of interest to query in the format `minLon,minLat,maxLon,maxLat`. Returns images that view any portion of the specified area.","schema":{"type":"string"}},{"name":"p","required":false,"in":"query","description":"A point of interest to query with an optional radius search parameter in the format `longitude,latitude[,radiusMeters]`. Returns images that view any portion of the specified point or radius area.","schema":{"type":"string"}},{"name":"heading","required":false,"in":"query","description":"Camera heading in degrees, expressed as an inclusive range [hmin, hmax], or as a single value.\nRange: [0, 360), where 0 is north, 90 is east, etc.\nBy default, no filter is applied.\nNote that a slight margin is applied to the edges to avoid filtering images at the edges of the range.","schema":{"type":"string"}},{"name":"pitch","required":false,"in":"query","description":"Camera angle below horizontal in degrees, expressed as an inclusive range [pmin, pmax], or as a single value.\nRange: [-135, 45], where -90 is directly downward (nadir), -60 is oblique, and -30 is more horizontal.\nBy default, no filter is applied.\nNote that a slight margin is applied to the edges to avoid missing images at the edges of the range.","schema":{"type":"string"}},{"name":"altitude","required":false,"in":"query","description":"Camera altitude above ground level in meters, expressed as an inclusive range [amin, amax], or as a single value.\nRange: [0, 10000], where 0 is ground level and 10000m is the practical maximum.\nBy default, no filter is applied.\nNote that a slight margin is applied to the edges to avoid missing images at the edges of the range.","schema":{"type":"string"}},{"name":"captured_at","required":false,"in":"query","description":"Image capture timestamp, expressed as an inclusive range [start, end], or as a single value.\nFormat: Any valid JavaScript date format (e.g., \"2023-01-01T00:00:00Z\", \"2023-01-01\", \"Jan 1, 2023\").\nBy default, no filter is applied.","schema":{"type":"string"}},{"name":"capture_type","required":false,"in":"query","description":"Filter by image capture type(s). Can be a single type or comma-separated list.\nValid values: panorama, orthomosaic, oblique.\nExample: \"panorama\" or \"panorama,oblique\".\nBy default, no filter is applied.","schema":{"type":"string"}},{"name":"focused","required":false,"in":"query","description":"Filtering mode: 'none' (no filtering), 'focused' (prioritize images where the point/area of interest is prominently featured), or '5-view' (return up to 5 images representing different viewing angles: nadir, north, east, south, west). Note: pagination is not supported for 'focused' and '5-view' modes.","schema":{"default":"none","enum":["none","focused","5-view"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of features to return. The default is 50, the maximum is 100.","schema":{"minimum":1,"type":"integer"}},{"name":"cursor","required":false,"in":"query","description":"Pagination token for retrieving subsequent result sets. Obtained from previous response when additional results exist.","schema":{"pattern":"^[aV64kbEPFOzgpjAGnN710Bvw8sucxrIQyXtdRJfMqK39CZUhoiLS2DWeH5mYlT]+$","type":"string"}},{"name":"f","required":false,"in":"path","description":"Response format type","schema":{"enum":["application/geo+json","application/json","text/html"],"type":"string"}},{"name":"Accept","in":"header","description":"Response format (unless specified by the `f` parameter)","required":false,"schema":{"type":"string","enum":["application/geo+json","application/json","text/html","*/*"]}},{"name":"Authorization","in":"header","description":"Bearer token for authenticated requests","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrientedImageCollectionItemsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"401":{"description":"Unauthorized"},"406":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}}},"summary":"Retrieve image features from a collection","tags":["OGC API"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.spexi.com/api-reference/standard-images-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.