LocalHeroes
Public API v1

Developers

Read-only access to matches, tournaments, grounds and player stats.

Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer lh_YOUR_API_KEY

Keys are currently issued by the LocalHeroes team — contact us or ask your platform admin. Keys are stored hashed on our side; treat yours like a password. All v1 endpoints are read-only (read scope).

Rate limits

Default is 60 requests/minute per key (a fixed 60-second window; higher limits on request). Responses include X-RateLimit-Limit and X-RateLimit-Remaining; exceeding the limit returns 429 with a Retry-After header.

Endpoints

EndpointDescriptionQuery params
GET/api/public/v1/matchesList matches (newest first).sport, status (setup|live|super_over|completed|verified|disputed), ground, page, limit
GET/api/public/v1/matches/{id}Match detail — accepts the short id (e.g. yvxszz) or ObjectId. Includes live score snapshot, full scorecard and public stream pointer.—
GET/api/public/v1/tournamentsList tournaments.sport, status (upcoming|ongoing|completed), page, limit
GET/api/public/v1/tournaments/{id}Tournament detail with fixtures and standings.—
GET/api/public/v1/groundsList approved grounds.sport, city, page, limit
GET/api/public/v1/grounds/{id}Ground detail by slug or ObjectId — facilities, hours, review aggregate.—
GET/api/public/v1/players/{shortId}Public player profile & per-sport stats by the player short id (or ObjectId).—

Every success response uses the envelope { "data": ..., "meta": { ... } }; errors use { "error": { "code", "message" } }. Absent values are null, never missing keys.

Example

curl -H "Authorization: Bearer lh_YOUR_API_KEY" \
  "https://localheroes.example/api/public/v1/matches?sport=cricket&status=live&limit=10"
{
  "data": [
    {
      "id": "yvxszz",
      "sportId": "cricket",
      "status": "live",
      "format": "t20",
      "teams": [{ "name": "Street Kings" }, { "name": "Turf Titans" }],
      "score": {
        "team1": { "runs": 142, "wickets": 5, "overs": 17.3 },
        "team2": null,
        "result": null,
        "winner": null
      },
      "venue": "Central Turf",
      "scheduledAt": "2026-07-20T14:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 10, "total": 1, "apiVersion": "v1" }
}