> For the complete documentation index, see [llms.txt](https://learn.spexi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.spexi.com/api-reference/quick-start.md).

# Quick Start

This guide demonstrates the basic Spexi Image API workflow, from authentication through image retrieval. Complete the following steps to make your first successful API request.

### Prerequisites

An active API key is required for all requests. If you have not yet generated an API key, refer to the [Authentication](/api-reference/authentication.md) section for detailed instructions.

### Basic Workflow

The standard API workflow consists of two primary steps: discovering available collections and querying specific imagery within those collections.

#### Step 1: Discover Available Collections

Begin by retrieving a list of imagery collections accessible through your account:

```bash
curl -X GET "https://api-world.spexi.com/api/ogc/v1/collections" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The response contains collection metadata including:

* **id** - unique identifier required for subsequent queries
* **name** - descriptive collection title
* **extent** - geographic boundaries and temporal coverage

#### Step 2: Query Collection Items

Select a collection ID from the previous response and retrieve imagery from that collection:

```bash
curl -X GET "https://api-world.spexi.com/api/ogc/v1/collections/COLLECTION_ID/items?p=-123.103865,49.27332,25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Replace `COLLECTION_ID` with the appropriate identifier from your collections response.

### Filtering Results

Basic queries may return extensive result sets. Apply query parameters to refine results based on your requirements.

#### Spatial Filtering

Filter images by geographic location using point queries:

```bash
curl -X GET "https://api-world.spexi.com/api/ogc/v1/collections/COLLECTION_ID/items?p=-123.103865,49.27332,25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This query returns images containing the specified coordinate (longitude -122.4194, latitude 37.7749) with a 100-meter buffer radius.

#### Intelligent Filtering

Apply the focused parameter to retrieve only the most relevant imagery for your area of interest:

```bash
curl -X GET "https://api-world.spexi.com/api/ogc/v1/collections/COLLECTION_ID/items?p=-123.103865,49.27332,25&focused=focused" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The focused parameter applies advanced filtering algorithms to select optimal imagery from potentially large datasets.

### Response Format

The API returns data in GeoJSON format. Each image appears as a feature containing:

* **geometry** - geographic footprint representing the ground area captured
* **properties** - comprehensive metadata including flight parameters and capture information
* **links** - array of related resources, including direct download URLs

Locate the download link by identifying the object with `"title": "Raw Image"` and `"type": "image/jpeg"`.

### Pagination

Large result sets are delivered using cursor-based pagination. When additional results are available, the response includes a next link:

json

```json
{
  "links": [
    {
      "rel": "next",
      "href": "https://api-world.spexi.com/api/ogc/v1/collections/COLLECTION_ID/items?cursor=pagination_token"
    }
  ]
}
```

Use the provided href URL to retrieve subsequent result pages.

### Next Steps

After completing these basic operations, explore additional functionality:

* [**Core Concepts**](/api-reference/core-concepts.md) - detailed explanation of collections and filtering mechanisms
* [**Use Cases and Examples**](/api-reference/code-examples.md) - practical implementation scenarios
* [**Standard Images API**](/api-reference/standard-images-api.md) - comprehensive parameter reference and advanced query options