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

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

• 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