# 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: ```bash curl -X GET "https://api-world.spexi.com/api/ogc/v1/collections" \ -H "Authorization: Bearer YOUR_API_KEY" ``` 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: ```bash curl -X GET "https://api-world.spexi.com/api/ogc/v1/collections/COLLECTION_ID/items?p=-123.103865,49.27332,25" ``` Apply focused filtering: ```bash curl -X GET "https://api-world.spexi.com/api/ogc/v1/collections/COLLECTION_ID/items?p=-123.103865,49.27332,25&focused=focused" ``` Request representative views: ```bash curl -X GET "https://api-world.spexi.com/api/ogc/v1/collections/COLLECTION_ID/items?p=-123.103865,49.27332,25&focused=5-view" ``` **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. --- # 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/core-concepts.md?ask= ``` 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.