# Filtering & Searching Data

Many Cineamo API endpoints support filtering to help you retrieve specific data.

## Query Parameters

Filters are applied using query parameters in the URL.

### Example

```bash
curl -X GET "https://api.cineamo.com/api/v1/movies?status=active&genre=action" \
  -H "Authorization: Bearer your_access_token"
```

## Common Filter Parameters

### Date Filters

Filter by date ranges using ISO 8601 format:

```bash
# Movies released after a specific date
?release_date_from=2024-01-01

# Movies released within a date range
?release_date_from=2024-01-01&release_date_to=2024-12-31
```

### Status Filters

Filter by resource status:

```bash
# Active movies only
?status=active

# Multiple statuses (comma-separated)
?status=active,upcoming
```

### Search Filters

Search across multiple fields:

```bash
# Search by title
?search=star+wars

# Search with exact match
?title=Star+Wars
```

### Sorting

Sort results using the `sort` parameter:

```bash
# Sort by release date (ascending)
?sort=release_date

# Sort by release date (descending)
?sort=-release_date

# Multiple sort fields
?sort=-popularity,release_date
```

## Filter Operators

Some endpoints support advanced filter operators:

| Operator | Description | Example |
|----------|-------------|---------|
| `eq` | Equal to | `?price[eq]=10` |
| `ne` | Not equal to | `?status[ne]=inactive` |
| `gt` | Greater than | `?price[gt]=10` |
| `gte` | Greater than or equal | `?price[gte]=10` |
| `lt` | Less than | `?price[lt]=100` |
| `lte` | Less than or equal | `?price[lte]=100` |
| `in` | In array | `?genre[in]=action,comedy` |
| `nin` | Not in array | `?genre[nin]=horror` |

## Combining Filters

You can combine multiple filters:

```bash
curl -X GET "https://api.cineamo.com/api/v1/movies?\
status=active&\
genre=action&\
release_date_from=2024-01-01&\
sort=-popularity&\
limit=50" \
  -H "Authorization: Bearer your_access_token"
```

## Filter Examples by Endpoint

### Movies

```bash
# Active action movies released in 2024, sorted by popularity
GET /api/v1/movies?status=active&genre=action&release_date_from=2024-01-01&sort=-popularity
```

### Showtimes

```bash
# Showtimes for a specific movie and cinema on a date
GET /api/v1/showtimes?movie_id=movie_123&cinema_id=cinema_456&date=2024-06-01
```

### Orders

```bash
# Completed orders in the last 30 days
GET /api/v1/orders?status=completed&created_from=2024-05-01&created_to=2024-05-31
```

## Best Practices

- **Use specific filters** to reduce response size and improve performance
- **Combine with pagination** for large result sets
- **Validate filter values** before making requests
- **Check endpoint documentation** for supported filters
- **Cache filtered results** when appropriate