# Image API

{% hint style="warning" %}
**Migration Notice**\
The [Standard Image API](https://learn.spexi.com/api-reference/standard-images-api) is being replaced by our new **Image API**.\
New integrations should use the updated API. Existing integrations should begin migrating.
{% endhint %}

The Image API provides direct access to Spexi's drone imagery library, allowing you to search, filter and download full resolution images available to your account. 

### Search Images

`GET /api/v1/image`

Search for drone images by geographic location and camera parameters. Returns a GeoJSON feature collection where each feature represents a single image with its footprint, metadata and download links.

#### 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
* **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 (at least one required):**

* **`p`** - find images containing a specific point. Format: **`lon,lat[,radiusMeters]`**
* **`bbox`** - retrieve images within a rectangular geographic area. Format: **`minLon,minLat,maxLon,maxLat`**
* **`polygon`** - retrieve images within a polygon area. Format: WKT

**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

**Smart Filtering:**

* **`focused`** - prioritize images where the point/area of interest is prominently featured. Enabled by default -  set to **`false`** to return all spatially intersecting images

{% hint style="info" icon="lightbulb" %}
**Combine parameters wisely** - all filter parameters use AND logic. For example, `?pitch=-90&heading=0` returns only nadir images facing north that prominently feature your query area.
{% endhint %}

#### 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"`)

#### How Focused Filtering Works

By default, the API filters and ranks images based on how prominently your point or area of interest is featured in the frame, so you get the most relevant, well-framed images without manually sorting through all results.

The filtering works in three steps:

1. **Spatial filtering** - starts with all images whose footprint contains your POI or AOI
2. **Edge filtering** - removes images where your POI or AOI is too close to the edge of the frame
3. **Focus scoring** - ranks remaining images based on how prominently the POI or AOI is featured, only returning images above a quality threshold

> Set **`focused = false`** if you need all spatially intersecting images regardless of framing - for example in systematic processing or full coverage extraction workflows.

## GET /developer-api/api/v1/image

> Search images

```json
{"openapi":"3.0.3","info":{"title":"Spexi Developer API","version":"1.0.0"},"servers":[{"url":"https://world.spexi.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication. Use pk_* keys for public/read-only access, sk_* keys for full access."}},"schemas":{"ImageSearchResponse":{"type":"object","properties":{"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 (footprint)."},"properties":{"type":"object","properties":{"id":{"type":"string","description":"Encoded image identifier (SID)."},"key":{"type":"string","description":"Unique identifier for the image."},"url":{"type":"string","format":"uri","description":"S3 URL to the image."},"captureType":{"type":"string","description":"Type of image capture (e.g., panorama, orthomosaic, oblique)."},"heading":{"type":"number","description":"Camera heading in degrees [0, 360), 0 is north."},"pitch":{"type":"number","description":"Camera angle below horizontal in degrees [-135, 45], -90 is nadir."},"roll":{"type":"number","description":"Camera roll in degrees."},"altitude":{"type":"number","description":"Altitude above ground level in meters."},"tag":{"type":"string","description":"Optional tag for grouping images."},"attributes":{"type":"object","additionalProperties":{},"description":"Additional metadata stored as JSON."},"capturedAt":{"type":"string","description":"Timestamp when image was captured."},"processedAt":{"type":"string","description":"Timestamp when image was processed."},"cameraPosition":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{}},"required":["type","coordinates"],"description":"2D point location of the camera at time of capture."},"distance":{"type":"number","description":"Distance in meters from the query point (only present when querying by point)."}},"required":["id","key","url","captureType","heading","pitch","roll","altitude","capturedAt","processedAt","cameraPosition"]},"links":{"type":"array","items":{"type":"object","properties":{"rel":{"type":"string","description":"Link relation type."},"href":{"type":"string","format":"uri","description":"URL of the linked resource."},"type":{"type":"string","description":"Media type of the linked resource."},"title":{"type":"string","description":"Human-readable title for the link."}},"required":["rel","href"]},"description":"Links to image variants."}},"required":["id","type","geometry","properties"]}},"next":{"type":"string","format":"uri","description":"URL to fetch the next page of results, if more exist."},"numberReturned":{"type":"number","description":"The number of features in the response."}},"required":["type","features","numberReturned"]}}},"paths":{"/developer-api/api/v1/image":{"get":{"operationId":"ImageController_searchImages","parameters":[{"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":"bbox","required":false,"in":"query","description":"An area of interest to query in the format `minLon,minLat,maxLon,maxLat`.","schema":{"type":"string"}},{"name":"polygon","required":false,"in":"query","description":"Polygon coordinates to query, in WKT format. Maximum polygon bounding box area: 1 km².","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":"limit","required":false,"in":"query","description":"Maximum number of images to return. The default is 100.","schema":{"minimum":1,"maximum":1000,"default":100,"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":"focused","required":false,"in":"query","description":"Apply advanced filtering to prioritize images where the point/area of interest is prominently featured.","schema":{"default":true,"oneOf":[{"type":"boolean"},{"type":"string"}]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchResponse"}}}}},"summary":"Search images","tags":["Image"]}}}}
```

### Search Multi-View Images

`GET /api/v1/image/multi-view`

Returns up to 5 images representing diverse viewing angles of a location - nadir, north, east, south, and west. The endpoint automatically selects the best image for each direction, prioritizing well-framed shots where your location is prominently featured. Use this endpoint when you need a quick, complete picture of a specific location from all directions in a single call.

#### Common Use Cases

* **Site inspection** - get a complete visual picture of a location from all directions
* **Visual verification** - confirm site conditions from multiple perspectives
* **Reporting** - quickly gather a representative set of images of a location for a report or presentation
* **Feasibility assessment** - get a quick multi-angle overview of a site before committing to deeper analysis

#### Parameters

Since the endpoint automatically handles image selection and quality filtering, only spatial and temporal parameters are supported. For more control over filtering, such as camera angle, heading, or capture type, use the [Search Images](#search-images) endpoint instead.

**Spatial (at least one required):**

* `p` - find images of a specific point (with optional buffer radius). Format: `lon,lat[,radiusMeters]`
* `bbox` - retrieve images within a rectangular geographic area. Format: `minLon,minLat,maxLon,maxLat`
* `polygon` - retrieve images within a polygon area. Format: WKT

**Temporal:**

* `captured_at` - filter by image capture date. Format: `start,end` or single value

#### Response Highlights

The response structure is identical to the Search Images endpoint. Each feature includes geometry, metadata, and download links.

## GET /developer-api/api/v1/image/multi-view

> Search multi-view images

```json
{"openapi":"3.0.3","info":{"title":"Spexi Developer API","version":"1.0.0"},"servers":[{"url":"https://world.spexi.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication. Use pk_* keys for public/read-only access, sk_* keys for full access."}},"schemas":{"ImageSearchResponse":{"type":"object","properties":{"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 (footprint)."},"properties":{"type":"object","properties":{"id":{"type":"string","description":"Encoded image identifier (SID)."},"key":{"type":"string","description":"Unique identifier for the image."},"url":{"type":"string","format":"uri","description":"S3 URL to the image."},"captureType":{"type":"string","description":"Type of image capture (e.g., panorama, orthomosaic, oblique)."},"heading":{"type":"number","description":"Camera heading in degrees [0, 360), 0 is north."},"pitch":{"type":"number","description":"Camera angle below horizontal in degrees [-135, 45], -90 is nadir."},"roll":{"type":"number","description":"Camera roll in degrees."},"altitude":{"type":"number","description":"Altitude above ground level in meters."},"tag":{"type":"string","description":"Optional tag for grouping images."},"attributes":{"type":"object","additionalProperties":{},"description":"Additional metadata stored as JSON."},"capturedAt":{"type":"string","description":"Timestamp when image was captured."},"processedAt":{"type":"string","description":"Timestamp when image was processed."},"cameraPosition":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{}},"required":["type","coordinates"],"description":"2D point location of the camera at time of capture."},"distance":{"type":"number","description":"Distance in meters from the query point (only present when querying by point)."}},"required":["id","key","url","captureType","heading","pitch","roll","altitude","capturedAt","processedAt","cameraPosition"]},"links":{"type":"array","items":{"type":"object","properties":{"rel":{"type":"string","description":"Link relation type."},"href":{"type":"string","format":"uri","description":"URL of the linked resource."},"type":{"type":"string","description":"Media type of the linked resource."},"title":{"type":"string","description":"Human-readable title for the link."}},"required":["rel","href"]},"description":"Links to image variants."}},"required":["id","type","geometry","properties"]}},"next":{"type":"string","format":"uri","description":"URL to fetch the next page of results, if more exist."},"numberReturned":{"type":"number","description":"The number of features in the response."}},"required":["type","features","numberReturned"]}}},"paths":{"/developer-api/api/v1/image/multi-view":{"get":{"operationId":"ImageController_searchMultiViewImages","parameters":[{"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 representing diverse viewing angles of the specified point.","schema":{"type":"string"}},{"name":"bbox","required":false,"in":"query","description":"An area of interest to query in the format `minLon,minLat,maxLon,maxLat`.","schema":{"type":"string"}},{"name":"polygon","required":false,"in":"query","description":"WKT POLYGON to query. Converted to bounding box for search, but original polygon used for highlighting. Maximum bbox area: 1 km².","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"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchResponse"}}}}},"summary":"Search multi-view images","tags":["Image"]}}}}
```

### Downloading Images

Both the Search Images and Multi-View endpoints return features with a `links` array containing ready-to-use download URLs. Each feature includes two download options:

* **Original image** (`rel: "original"`) - the full resolution image as captured
* **Zoomed image** (`rel: "zoomed"`) - the image automatically cropped and zoomed to your area of interest

To download, find the relevant link in the `links` array by its `rel` value and use the `href` directly.

#### Implementation Notes

💡 **Authentication** - download URLs require the same API key authentication. Include your `x-api-key` header when making download requests.

💡 **Image files** - images are delivered as high-resolution JPEG files with EXIF and XMP metadata embedded.