eSIMBench API

A free public JSON API for the live travel-eSIM benchmark. Grab a key in one click, hit any endpoint, 500 requests/hour. No payment, no premium tier — if you need more, message @aliakbaraffinco on Telegram. Please link back to esimbench.com when you publish scores.

1. Getting started

Grab a key (no email, no verification — one HTTP request):

curl "https://esimbench.com/api/v1/keys/new?name=YourApp"

Use it as a Bearer token on every other endpoint:

curl -H "Authorization: Bearer esb_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://esimbench.com/api/v1/score/airalo"

2. Authentication

Send your key in the Authorization header as Bearer <key>. Never put it in a query string. Missing/invalid key → 401. Lost the key? Just generate a new one.

3. Rate limits

500 requests / hour per key. Every response includes:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 342
X-RateLimit-Reset: 1717200000   (epoch seconds when the bucket rolls over)

Over the limit → 429 with a friendly reset message. Buckets are hourly (KV-backed) so you reset on the hour mark, not 60 min after first call.

4. Endpoints

`GET /api/v1/keys/new?name=YourApp`

No auth. Returns a new key. name is optional (label only; no PII).

{
  "key": "esb_live_…",
  "name": "YourApp",
  "created_at": "2026-06-01",
  "rate_limit": "500 requests / hour",
  "docs": "https://esimbench.pages.dev/api/docs",
  "source": "esimbench.com"
}

`GET /api/v1/leaderboard`

The live leaderboard — every active provider, ranked. Edge-cached 1h.

{
  "quarter": "live",
  "updated_at": "2026-06-01T…",
  "source": "esimbench.com",
  "providers": [
    { "rank": 1, "provider": "yesim", "score": 77.8, "grade": "B+", "rank_change": null },
    …
  ]
}

`GET /api/v1/score/{provider}`

Full scorecard data for one provider — bench score, grade, rank, all 8 dimensions.

curl -H "Authorization: Bearer esb_live_…" \
  "https://esimbench.com/api/v1/score/yesim"

{
  "provider": "yesim",
  "bench_score": 77.8,
  "grade": "B+",
  "rank": 1,
  "rank_change": null,
  "dimensions": {
    "app_quality":       { "score": 79.6, "weight": 0.10, "confidence": "high" },
    "fair_use_refunds":  { "score": 90,   "weight": 0.10 },
    "hotspot_tethering": { "score": 50,   "weight": 0.05 }
  },
  "pending_dimensions": ["speed_coverage", "pricing_value", "plan_flexibility", "customer_support", "five_g_access"],
  "quarter": "live",
  "updated_at": "2026-06-01T…",
  "source": "esimbench.com",
  "scorecard_url": "https://esimbench.pages.dev/provider/yesim"
}

Pending dimensions are listed honestly — they're excluded from the weighted bench (never counted as zero). When a provider doesn't have enough verified dimensions to grade fairly, grade is "NR" (Not Rated).

`GET /api/v1/score/{provider}/dimension/{dimension}`

One dimension detail — score, weight, confidence, raw_value.

Dimensions: speed_coverage, pricing_value, plan_flexibility, app_quality, customer_support, hotspot_tethering, five_g_access, fair_use_refunds.

`GET /api/v1/use-case/{slug}`

The ranked list of providers for a use case (video-calls, digital-nomads, …) with re-weighted scores.

5. Embed badges

A 3-line iframe drops a live scorecard on any page. No API key required, edge-cached.

<iframe src="https://esimbench.com/embed/badge/airalo"
        width="340" height="120" frameborder="0" loading="lazy"
        title="Airalo eSIM scorecard — eSIMBench"></iframe>

Query params: ?theme=light|dark, ?show=grade|score|both, ?highlight=<dimension_id>. Or use the visual builder if you'd rather click around.

6. Attribution

Please credit eSIMBench when you publish scores. Embed badges link back automatically; for API responses, surface the scorecard_url field as a clickable link. It's how this project stays free.

7. Contact

API questions, higher limits, partnerships → Telegram @aliakbaraffinco.