VOX EARTH

Developers

Embed live global polls on your site or blog, and read aggregated opinion data through the public API. Free for editorial and non-commercial use — attribution appreciated.
（Vox Earthの投票はどのサイトにも埋め込めます。集計データは公開APIから取得できます）

1. Embed a poll

Every poll page has a “Copy embed code” button. The code is a plain iframe plus an optional auto-resize snippet — it degrades gracefully to a fixed height on platforms that strip scripts.

<iframe src="https://vox.earth/embed/12345"
  style="width:100%;max-width:420px;border:none;border-radius:16px;"
  height="560" loading="lazy" allow="geolocation"></iframe>
<script>window.addEventListener("message",function(e){
  if(e.origin!=="https://vox.earth"||!e.data||e.data.type!=="voxearth:resize")return;
  document.querySelectorAll('iframe[src*="vox.earth/embed/'+e.data.pollId+'"]')
    .forEach(function(f){f.style.height=e.data.height+"px"})});</script>

URL parameters

Parameter	Effect
`?theme=light`	White widget for light-colored sites
`?results=1`	Read-only results view (no voting UI) — for articles reporting an outcome. Includes a per-country majority breakdown.

Auto-resize protocol

The widget posts {type:"voxearth:resize", pollId, height} to its parent via postMessage whenever its content height changes. Always verify e.origin === "https://vox.earth".

2. oEmbed

Platforms that support oEmbed discovery can turn a pasted poll URL into the widget automatically. Poll pages carry a discovery <link> tag, or call the endpoint directly:

GET https://vox.earth/api/oembed?url=https://vox.earth/12345&format=json

{
  "version": "1.0",
  "type": "rich",
  "provider_name": "Vox Earth",
  "title": "Should tipping culture be abolished?",
  "html": "<iframe src=\"https://vox.earth/embed/12345\" ...>",
  "width": 420,
  "height": 560,
  "thumbnail_url": "https://.../og/12345.png"
}

3. Read API

Read-only JSON endpoints, CORS-enabled (Access-Control-Allow-Origin: *). No API key required.

GET /api/polls/{id}

Poll metadata: question, options, category, expiry.

GET /api/polls/{id}/stats

World and per-country vote aggregates. Option indexes refer to the options array.

GET https://vox.earth/api/polls/12345/stats

{
  "poll_id": "12345",
  "question": "…",
  "options": ["Yes", "No"],
  "world":     { "total": 1204, "options": { "0": 512, "1": 692 } },
  "countries": { "JP": { "total": 210, "options": { "0": 80, "1": 130 } }, … },
  "note": "Counts reflect Vox Earth participants, not representative national surveys."
}

GET /api/series/{seriesId}/trend

Round-by-round aggregates for tracked questions (opinion over time). Each round is an independent poll with its own voting window.

{
  "series_id": 1,
  "rounds": [
    { "round": 1, "poll_id": "12345", "total": 640,
      "options": { "0": 320, "1": 320 },
      "started_at": "2026-03-01T00:00:00Z", "ends_at": "2026-03-08T00:00:00Z" },
    …
  ]
}

Methodology note: Vox Earth counts are self-selected participant data, not representative national surveys. When publishing numbers, please state “according to Vox Earth participants” and include the sample size (total). Country-level figures with fewer than 5 votes should be treated as anecdotal.

Fair use

Cache responses for at least 60 seconds (responses carry Cache-Control headers). Heavy automated polling may be rate-limited. For partnerships, higher-volume access or data exports, contact us via the guide page.