# Python SDK

> The official sightradar package for Python. Zero runtime dependencies, typed models, and typed exceptions for every non-2xx response.

Source: https://sightradar.com/docs/sdks/python

```bash
pip install sightradar
```

Source and issues: [github.com/sightradar-hq/sightradar-python](https://github.com/sightradar-hq/sightradar-python). MIT licensed, built on the standard library only.

## Authenticate

```python
from sightradar import SightRadar

sr = SightRadar(api_key="frs_...")   # or: SightRadar() with SIGHTRADAR_API_KEY set
```

## Core workflow

```python
# 1. Create a collection to hold faces.
sr.create_collection("event-2026")

# 2. Index faces from photos (URL, GCS key, or a local file).
sr.index("event-2026", url="https://example.com/group.jpg")
sr.index("event-2026", file="/path/to/photo.jpg", photo_id="img-42")

# 3. Search the collection with one selfie.
result = sr.search("event-2026", url="https://example.com/selfie.jpg")
if result.found:
    for m in result.matches:
        print(m.photo_id, round(m.similarity, 3))
else:
    print("no match:", result.reason)
```

## Stateless operations

```python
# Detect and quality-gate faces in an image. Nothing is stored.
det = sr.detect(url="https://example.com/photo.jpg")
print(det.detected_face_count, det.gated_face_count)

# 1:1 verification between two faces.
cmp = sr.compare(
    source_url="https://example.com/a.jpg",
    target_url="https://example.com/b.jpg",
)
print(cmp.match, cmp.similarity)
```

## Selfies and search-by-id

```python
reg = sr.register_selfie("event-2026", url="https://example.com/selfie.jpg", user_id="u_42")
hits = sr.search_by_id("event-2026", point_id=reg.point_id, limit=50)
```

## Account

```python
print(sr.wallet().balance_credits)
print(sr.usage(days=30))
```

## Image inputs

Index, search, detect and register-selfie accept exactly one image source:

| Argument   | Meaning                                                             |
| ---------- | ------------------------------------------------------------------- |
| `url=`     | a public image URL                                                  |
| `gcs_key=` | a Google Cloud Storage object key                                   |
| `file=`    | a local path, `bytes`, or a file-like object, uploaded as multipart |

`search` additionally accepts `embedding=` (a 512-number list).

## Errors

Every non-2xx response raises a typed exception:

```python
from sightradar import (
    SightRadarError,            # base
    AuthenticationError,        # 401
    InsufficientCreditsError,   # 402
    NotFoundError,              # 404
    RateLimitError,             # 429
)

try:
    sr.describe_collection("missing")
except NotFoundError as e:
    print(e.status_code, e.message)
```

See [errors and status codes](/docs/errors) for what each status means.

## Method reference

| Method                                                                              | Endpoint                                       |
| ----------------------------------------------------------------------------------- | ---------------------------------------------- |
| `create_collection`, `list_collections`, `describe_collection`, `delete_collection` | [Collections](/docs/api/collections)           |
| `index`                                                                             | `POST /v1/collections/{id}/index`              |
| `search`                                                                            | `POST /v1/collections/{id}/search`             |
| `search_by_id`                                                                      | `POST /v1/collections/{id}/search-by-id`       |
| `register_selfie`                                                                   | `POST /v1/collections/{id}/selfies`            |
| `detect`                                                                            | `POST /v1/detect`                              |
| `compare`                                                                           | `POST /v1/compare`                             |
| `wallet`, `usage`                                                                   | [Wallet and usage](/docs/api/wallet-and-usage) |

Batches and webhooks are not wrapped yet; call them over REST with any HTTP client. See [batch and webhooks](/docs/guides/batch-and-webhooks).