Core Concepts
This section explains the fundamental concepts required to effectively use Spexi APIs. Understanding these concepts will enable you to structure queries efficiently and interpret API responses.
Understanding Collections
Collections represent organized datasets of related imagery within the Spexi platform. The OGC Features standard defines collections as containers that group similar geospatial features based on shared characteristics or logical relationships.
What Collections Represent
In the Spexi context, collections typically organize imagery by:
Geographic region - imagery from specific areas or administrative boundaries
Product type - different categories of imagery products as they become available
Collection Metadata
Each collection includes descriptive metadata that helps determine its relevance for your use case:
id - unique identifier used in all API requests for that collection
title - human-readable name describing the collection contents
description - detailed information about the imagery
extent - geographic boundaries of the imagery within the collection
links - related resources including the items endpoint for querying collection imagery
Working with Collections
The collections endpoint serves as the entry point for all API interactions:
Review collection metadata to identify datasets relevant to your requirements before querying specific imagery. Collection IDs remain stable over time, enabling reliable programmatic access to specific datasets.
Standard Images
Standard images represent the core imagery product available through the Spexi APIs. These images are captured directly by drones and serve as the foundation for derived products such as panoramas and orthomosaics.
Image Characteristics
Standard images contain the following key attributes:
Spatial Properties:
Latitude and longitude - precise GPS coordinates of the camera position at capture time
Altitude - height above ground level during image capture
Footprint geometry - geographic area visible in each image
Camera Parameters:
Pitch - camera angle relative to horizontal plane (typically -90° to -30°)
Heading - compass direction the camera was facing (0° to 360°, where 0° represents north)
Metadata:
Capture timestamp - precise date and time of image acquisition
EXIF data - comprehensive technical metadata embedded in image files
File format - images are delivered as high-resolution JPEG files
Image Coverage and Overlap
Drone surveys typically capture images with significant overlap to ensure complete area coverage. This approach results in multiple images containing the same geographic features, often from different angles and perspectives. While comprehensive, this overlap can complicate workflows that require specific imagery for particular locations.
The Focused Parameter
The focused parameter addresses the challenge of selecting relevant imagery from datasets with extensive overlap. This feature applies intelligent filtering algorithms to identify the most appropriate images for your specified area of interest.
Filtering Modes
The focused parameter supports three distinct modes:
none (default)
Returns all images that meet the specified query parameters
No additional filtering applied
Useful for comprehensive analysis requiring all available perspectives
focused
Applies advanced filtering to select images where the specified point or area is prominently featured
Reduces result sets to the most relevant imagery for the query location
Recommended for most practical applications
5-view
Returns up to five representative images from different perspectives (cardinal directions plus nadir)
Provides comprehensive coverage while maintaining manageable result sets
Ideal for applications requiring multiple viewpoints of the same location
Usage Examples
Basic query without filtering:
Apply focused filtering:
Request representative views:
When to Use Focused Filtering
The focused parameter is particularly valuable when:
Working with point or small bounding box queries where you need imagery of a specific location
Developing applications that display imagery to end users
Processing large datasets where computational efficiency is important
Creating visualizations or analyses that require the best available imagery for each location
Note that focused filtering is only effective when combined with spatial query parameters such as point or bounding box queries. The filtering algorithms require geographic context to determine image relevance.
Last updated