# 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
```

Published on PyPI as [sightradar](https://pypi.org/project/sightradar/). 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, connected-storage 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.score, 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", "u_42", url="https://example.com/selfie.jpg")  # user_id is required
hits = sr.search_by_id("event-2026", reg.point_id, limit=50)
```

## Deleting and restoring

```python
receipt = sr.delete_collection("event-2026")          # soft: receipt.restorable is True
sr.restore_collection("event-2026")
sr.delete_collection("event-2026", compliance=True)    # audited erasure, not restorable
status = sr.deletion_status("event-2026")             # status.erased once phase=completed and verified_zero
sr.delete_photo("event-2026", "img-42")               # one photo's faces; restore_photo undoes a soft delete
```

## Batches and webhooks

```python
wh = sr.register_webhook("https://your.app/webhooks/sightradar")   # wh.secret is returned once
batch = sr.submit_batch("event-2026", "index",
                        [{"url": "https://example.com/1.jpg", "external_id": "img-1"}],
                        webhook_endpoint_id=wh.webhook_endpoint_id)
status = sr.get_batch(batch.batch_id)                 # .succeeded / .failed / .pending / .done
page = sr.get_batch_photos(batch.batch_id)            # per-photo results, keyset paginated

from sightradar import verify_webhook_signature
ok = verify_webhook_signature(stored_secret, request.headers["X-SightRadar-Timestamp"],
                              request.get_data(), request.headers["X-SightRadar-Signature"])
```

## Retries and idempotency

Retries are off by default. `SightRadar(max_retries=3)` retries `429`, `502` and `503` with exponential backoff for GET requests. It retries a mutating call only when you pass `idempotency_key=`, so pass one on `index` and `register_selfie` when you want those calls retried safely.

## 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=` | an object key in a storage bucket connected to your account         |
| `file=`    | a local path, `bytes`, or a file-like object, uploaded as multipart |

`search` additionally accepts `embedding=` (a 512-number list). `register_selfie` also requires `user_id` (positional) and accepts `selfie_id=`.

## 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`, `collection_metrics`           | [Collections](/docs/api/collections)           |
| `delete_collection(immediate=, compliance=, intent=)`, `restore_collection`, `deletion_status` | collection delete lifecycle                    |
| `delete_photo(immediate=, compliance=)`, `restore_photo`                                       | per-photo faceprints                           |
| `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`                             |
| `submit_batch`, `get_batch`, `get_batch_photos`, `list_batches`                                | [Batch](/docs/api/batch)                       |
| `register_webhook`, `list_webhooks`, `delete_webhook`, `verify_webhook_signature`              | [Webhooks](/docs/api/webhooks)                 |
| `wallet`, `usage`                                                                              | [Wallet and usage](/docs/api/wallet-and-usage) |

Typed models: `Collection`, `SearchResult` / `Match` (`.score`, with `.similarity` kept as an alias), `IndexResult`, `SelfieResult`, `CompareResult`, `DetectResult`, `Batch`, `Webhook`, `DeletionReceipt`, `DeletionStatus`, `Wallet`. Every model exposes the untouched payload as `.raw`. Requires Python 3.8 or newer; current release 1.1.2.
