# Tipsme Football Data API

> Live scores, fixtures, statistics, lineups, head-to-head, odds and team logos. Plus and Pro also include AI reports, tip distribution, handicap, goals and corner analysis.

Base URL: https://api.tipsme.hk
Auth: `Authorization: Bearer <key>` (or `X-Api-Key: <key>`). Keys: https://tipsme.hk/developers/dashboard/keys
Only /v1/football/meta/* is keyless. Every other route returns 401 without a key.
Response shape: most endpoints use `{ "data": … }`. /matches adds pagination meta (page, pageSize, total, totalPages; page 1-based, pageSize defaults to 25 and is capped at 100). /matches/live is not paginated. /odds/exchange returns stored JSON directly.
Types: kickoffUtc is ISO-8601 UTC; historical analysis dates and labels retain stored formatting. Match scores/corners use "home-away" strings; analysis counts and odds can be numbers. Follow each endpoint schema. Accept-Language selects supported translations; AI reports provide en, zh-CN or zh-HK text (zh-TW uses traditional Chinese).
Each account may hold one unrevoked API key. Daily plan usage belongs to the account and survives key revocation/replacement: X-Quota-Limit/Remaining/Reset (per Hong Kong day, resets 00:00 HKT). Per-minute limits remain per key: X-RateLimit-Limit/Remaining/Reset. 429 carries Retry-After.
Every plan includes a free allowance of GET /v1/football/matches requests per account per Hong Kong day (Free 50, Plus 500, Pro 2,000; the live numbers are in /v1/football/meta/plans as tiers[].limits.freeMatchesDailyQuota). Query variants share that allowance; /matches/live and child routes do not qualify. The bonus is used first, then the account plan allowance. Both reset at midnight HKT; replacing a key resets neither. The per-minute limit still applies. Matching responses include X-Matches-Bonus-Limit/Remaining/Reset; X-Quota headers exclude the bonus.
Errors: RFC 9457 problem+json with a `code` field (invalid_parameter, unauthorized, key_invalid, key_expired, ip_not_allowed, tier_insufficient, not_found, rate_limited, quota_exceeded, upstream_malformed, upstream_unavailable); each `type` links to its explanation at https://tipsme.hk/developers/docs/errors#<code>. Successful empty collections return data: []; missing resources, including unpublished lineups or unavailable HKJC boards, may return 404. Null optional properties are omitted.
Plans: Free, Plus, Pro — https://tipsme.hk/developers/pricing. Analysis requires Plus or Pro. Other published endpoints are available on all plans. Each account permits one API key; allowances and per-minute rates differ. Paid plans renew automatically; cancellation keeps access until the paid period ends.

## Endpoints

- GET /v1/football/meta/limits; returns EnvelopeOfIReadOnlyListOfTierLimitsDto
- GET /v1/football/meta/plans; returns EnvelopeOfPricingDto
- GET /v1/football/matches/live — params: league?, status?; returns EnvelopeOfIReadOnlyListOfMatchDto
- GET /v1/football/matches — params: date?, league?, status?, page?, pageSize?, tz?; returns EnvelopeOfIReadOnlyListOfMatchDto
- GET /v1/football/matches/{matchId} — params: matchId; returns EnvelopeOfMatchDto
- GET /v1/football/matches/{matchId}/events — params: matchId; returns EnvelopeOfMatchEventsDto
- GET /v1/football/matches/{matchId}/statistics — params: matchId; returns EnvelopeOfMatchStatisticsDto
- GET /v1/football/matches/{matchId}/h2h — params: matchId; returns EnvelopeOfMatchH2hDto
- GET /v1/football/matches/{matchId}/lineups — params: matchId; returns EnvelopeOfMatchLineupsDto
- GET /v1/football/odds/bookmakers; returns EnvelopeOfIReadOnlyListOfBookmakerDto
- GET /v1/football/matches/{matchId}/odds — params: matchId; returns EnvelopeOfMatchOddsDto
- GET /v1/football/matches/{matchId}/odds/exchange — params: matchId
- GET /v1/football/matches/{matchId}/odds/kelly — params: matchId; returns EnvelopeOfKellyIndexDto
- GET /v1/football/matches/{matchId}/odds/hkjc — params: matchId; returns EnvelopeOfHkjcOddsBoardDto
- GET /v1/football/matches/{matchId}/odds/{market}/{bookmaker} — params: matchId, market, bookmaker; returns EnvelopeOfOddsMovementDto
- GET /v1/football/matches/{matchId}/analysis/ai-basic — params: matchId; returns EnvelopeOfMatchAiAnalysisDto; plans: Plus, Pro
- GET /v1/football/matches/{matchId}/analysis/ai-deep — params: matchId; returns EnvelopeOfMatchAiAnalysisDto; plans: Plus, Pro
- GET /v1/football/matches/{matchId}/analysis/tips-distribution — params: matchId; returns EnvelopeOfMatchTipsDistributionDto; plans: Plus, Pro
- GET /v1/football/matches/{matchId}/analysis/handicap — params: matchId; returns EnvelopeOfMatchHandicapAnalysisDto; plans: Plus, Pro
- GET /v1/football/matches/{matchId}/analysis/over-under — params: matchId; returns EnvelopeOfMatchOverUnderAnalysisDto; plans: Plus, Pro
- GET /v1/football/matches/{matchId}/analysis/corners — params: matchId; returns EnvelopeOfMatchCornerAnalysisDto; plans: Plus, Pro

## Typical flow

1. GET /v1/football/matches?date=YYYY-MM-DD&tz=480 (UTC offset in minutes; Hong Kong is +480) (or /matches/live) → take `data[].id`.
2. GET /v1/football/matches/{id}/odds → opening/closing prices per bookmaker; /odds/{market}/{bookmaker} for the full movement (markets: had, hdp, hilo; bookmaker ids from /odds/bookmakers).
3. GET /v1/football/matches/{id}/lineups, /events, /statistics, /h2h for depth.
4. Plus/Pro: GET /v1/football/matches/{id}/analysis/ai-basic, /ai-deep, /tips-distribution, /handicap, /over-under or /corners for analysis.
Match responses include homeLogo and awayLogo URLs built from the original team names under https://assets.tipsme.hk/UploadFolder/Teams/.

## More

- Full OpenAPI 3.1: https://tipsme.hk/api/openapi-v1.json
- Human docs: https://tipsme.hk/developers/docs
- Quickstart (with a no-code path): https://tipsme.hk/developers/quickstart