# padelgod

> A read-only HTTP feed of professional padel data: FIP rankings, player identity,
> results and partnership evidence. Responses are taken at a cut-off the caller
> chooses, and a cut-off in the past returns byte-identical data forever — so a
> client can publish a hash of what it received and let anyone recompute it.
> Authentication is a bearer key; the API lives at api.padelgod.io.

## Docs

- [API reference](https://padelgod.io/docs): the same material as a web page, with the parameter and error tables laid out.
- [Integration guide](https://padelgod.io/docs.md): endpoints, authentication, a worked example, the error table, and coverage figures including the fields that are empty.
- [Source code](https://github.com/gudenes/padelgod-api): the service itself, public.

## Endpoints

- [GET /v1/rankings](https://padelgod.io/docs.md): the ranked field at a cut-off. Requires `asOf` with an explicit UTC offset and `category` of `men` or `women`.
- [GET /v1/roster](https://padelgod.io/docs.md): rankings joined to player identity — legal name, display name, country, birthdate, coaches, photograph.
- [GET /v1/pairs](https://padelgod.io/docs.md): partnership evidence — counts of shared main-draw matches per player pair, with the date they last played together.

## Things a model should not get wrong about this feed

- `asOf` must carry an explicit UTC offset. A datetime without one is rejected with 400, deliberately: without the rule the same cut-off resolves to different instants depending on the server's region.
- Clients hash the `data` array, never the whole response. `meta.generatedAt` changes on every call and lives outside the payload for that reason.
- `elo` is present in every response but is `null` today. It will not be backfilled with a value derived from the ranking.
- `/v1/pairs` returns counts, not a named partner. Applying a threshold is the client's decision, published in the client's own methodology.
- Photographs are present for roughly 64% of the men's top 200 and 54% of the women's. `photoUrl: null` is an ordinary answer, not an error.
- A cut-off older than our history returns 422 with `no_snapshot_before` and an `earliest` field, not 404. History starts 2026-05-04.
- `externalId` is the FIP id on `/v1/roster` but our internal player id on `/v1/rankings`, which does not join the players table. The two cannot be joined on that field.