n8n-nodes-livetennisapi

This is an n8n community node for the Live Tennis API — real-time tennis scores, match data, player profiles, fixtures, rankings, head-to-head records and a 1968–2022 results archive across all 5 tours: ATP, WTA, Challenger, ITF and juniors.

n8n is a fair-code licensed workflow automation platform.

Version note: npm currently serves 0.1.0 while this repo is at 0.2.0 — newer releases are awaiting a publish-credential fix. To get the latest now, install from source (clone, npm install && npm run build, then npm install <path> from your n8n custom directory).

• Installation
• Credentials
• Operations
• Quotas and rate limits
• Authentication details
• Usage notes
• Compatibility
• Resources

Installation

Follow the installation guide in the n8n community nodes documentation. The package name is n8n-nodes-livetennisapi.

In short: Settings → Community Nodes → Install, enter n8n-nodes-livetennisapi, and restart if prompted. The Live Tennis API node then appears in the node picker.

Credentials

Sign up for a free API key (100 requests/day, 30/minute, no card) at livetennisapi.com/subscribe/free.

Create a Live Tennis API credential in n8n and paste the key (it looks like twjp_...). The node sends it as an X-API-Key header. The credential test performs a one-match list request.

Operations

| Resource | Operation | Endpoint | Plan | |---|---|---|---| | Match | Get Many | /matches | FREE — Status = Completed needs BASIC or any History plan | | Match | Get | /matches/{id} | FREE — market embed at PRO, analysis embed at ULTRA | | Match | Get Score | /matches/{id}/score | FREE | | Match | Get Statistics | /matches/{id}/statistics | ULTRA | | Player | Search | /players | FREE | | Player | Get | /players/{id} | FREE | | Fixture | Get Many | /fixtures | FREE | | H2H | Get | /h2h | BASIC, or any History plan — per-player stats block at ULTRA | | Archive | Get Many Matches | /history/archive/matches | BASIC, or any History plan | | Archive | Get Match | /history/archive/matches/{id} | BASIC, or any History plan | | Archive | Get Many Players | /history/archive/players | BASIC, or any History plan | | Archive | Get Career | /history/archive/career | BASIC, or any History plan | | Ranking | Get Many (rank-ordered listing) | /rankings?system= | PRO | | Ranking | Get for Player (point-in-time records) | /rankings?player= | ULTRA | | Status | Get | /health | no key needed |

Notes on the less obvious ones:

• Match → Get Many takes filters for tour (atp, wta, challenger, itf, juniors), country (3-letter IOC-style code), a from/to date window, and a player ID. Unknown filter values are a 400, never silently ignored.
• H2H and Archive → Get Career are keyed by name fragments (min 3 characters) — archive people have no roster IDs. An ambiguous fragment is refused with the candidate list rather than summing two people into one record.
• Archive covers ATP and WTA results 1968–2022 (1968-onward main draws, qualifying, challengers and futures). It is a separate ID space from live matches and ends where the API's own point-by-point coverage begins (2023).
• Ranking → Get Many lists exactly one system per call (atp, wta, itf_jt, itf_mt, itf_wt); UTR has no listing (it is a rating, not a ranking) and is read per player. Get for Player answers "what was the ranking as of a date" — everywhere else the API joins today's rank.

Quotas and rate limits

| Plan | Per minute | Per day | Price | |---|---|---|---| | FREE | 30 | 100 | $0 | | BASIC | 60 | 1,000 | $9.99/mo | | PRO | 300 | 10,000 | $29.99/mo | | ULTRA | 600 | 500,000 | $99.99/mo |

• On a FREE key (100 requests/day), poll no faster than every 15 minutes. For an always-on dashboard, BASIC is the recommended floor.
• Every response carries X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers; 429s carry Retry-After.
• The node turns API errors into actionable n8n errors instead of bare status codes:
  • Daily 429 — the error shows the daily limit and resets_at, the absolute ISO instant the quota resets (trust that instant, not an assumed fixed UTC boundary).
  • 429 abuse_throttled — keys that keep hammering the API after the cap is spent are blocked for 24 hours; the error converts retry_at_epoch to an ISO time and says to fix the retry loop (add a Wait node, back off on 429s).
  • Per-minute 429 — the error carries the Retry-After seconds.
  • 403 upgrade_required — the error names the tier that unlocks the operation and where to upgrade. It does not mean your key is invalid.

Authentication details

The API accepts Authorization: Bearer <key> (preferred for new integrations) and X-API-Key: <key>. This node sends X-API-Key. Keys are prefixed twjp_. Only /health is unauthenticated.

Usage notes

These reflect real behaviour of the live feed — the node passes the data through untouched:

• score.points are strings ("0", "15", "30", "40", "AD"), not numbers.
• score.server is null on roughly 7% of live reads — handle the null.
• score.games is [games_p1, games_p2], where each entry is a per-set array that grows as the match progresses.
• data_completeness.known / .of are null for doubles teams (with an explanatory note) — null means "not applicable", which is distinct from 0.
• The tour field on a response record is granular (challenger_men, juniors_girls) and uppercase for doubles teams (ATP). It is an opaque label — it is not the same vocabulary as the tour filter, which accepts exactly atp, wta, challenger, itf, juniors and returns a 400 on anything else.
• Fixture Get Many may occasionally include already-finished fixtures or return an empty list (a known upstream quirk); the node passes the response through as-is.
• Bulk completed-match paging (Get Many with Status = completed) is not available on the FREE tier at all — it returns a 403 upgrade_required. It needs the BASIC tier ($9.99/mo) or any History plan — upgrade at livetennisapi.com/subscribe/upgrade. Fetching a single completed match by ID with Get stays free.
• Return All pages through results 200 at a time with no delay between pages — one API request per page. On a large bucket that can hit the per-minute rate limit mid-pagination and fail with a 429, and repeated Return All runs over big result sets (completed matches can span thousands of records) can exhaust the FREE tier's 100 requests/day cap. Prefer Limit with an explicit value on large buckets, or use a higher plan tier.
• Archive serve statistics exist from 1991 onward only; earlier rows have stats: null (the era never recorded them — nothing is synthesised).

Compatibility

Requires n8n 1.x. Built declaratively with zero runtime dependencies.

Resources

• Live Tennis API documentation
• Get a free API key
• Live Tennis API Discord
• Live Tennis API on GitHub
• n8n community nodes documentation

Affiliate program

Know developers who need tennis data? The affiliate program pays 51% recurring commission for the life of every referred subscription — 30-day cookie, and the people you refer get 10% off.

License

MIT © Live Tennis API