{"openapi":"3.1.0","info":{"title":"The Hear API","version":"1.0.0","summary":"Live and historical front-page headlines from 20 countries, with AI overviews.","description":"Public, read-only HTTP API for [The Hear](https://www.thehear.org).\nEach call returns the current main headline for every monitored source in a country, plus AI-generated overviews of the headline landscape.\nNo authentication or API key is required. Use reasonable request rates.\n\nHuman docs: https://www.thehear.org/api\n\n## Calls\n- **snapshot** (default): current or historical main headlines, plus three AI overviews.\n- **daily-overviews**: AI daily overviews for a date range of at most 7 days.\n\n## Countries\n- `israel` — Israel (archive from 2024-07-04)\n- `china` — China (archive from 2024-09-07)\n- `finland` — Finland (archive from 2025-11-01)\n- `france` — France (archive from 2024-08-29)\n- `germany` — Germany (archive from 2024-07-29)\n- `india` — India (archive from 2024-09-05)\n- `iran` — Iran (archive from 2024-08-29)\n- `italy` — Italy (archive from 2024-08-28)\n- `japan` — Japan (archive from 2024-09-07)\n- `kenya` — Kenya (archive from 2025-11-13)\n- `lebanon` — Lebanon (archive from 2024-08-29)\n- `netherlands` — Netherlands (archive from 2024-09-05)\n- `palestine` — Palestine (archive from 2024-09-10)\n- `poland` — Poland (archive from 2024-08-30)\n- `russia` — Russia (archive from 2024-08-29)\n- `spain` — Spain (archive from 2024-09-05)\n- `turkey` — Turkey (archive from 2024-09-08)\n- `uk` — UK (archive from 2024-09-05)\n- `us` — US (archive from 2024-07-31)\n- `ukraine` — Ukraine (archive from 2024-09-05)","contact":{"name":"The Hear","url":"https://www.thehear.org/contact"},"license":{"name":"Terms of Use","url":"https://www.thehear.org/legal"}},"servers":[{"url":"https://www.thehear.org","description":"Production"}],"tags":[{"name":"Country view","description":"Front-page headlines and AI overviews for one country."}],"paths":{"/api/country-view/{country}":{"get":{"tags":["Country view"],"operationId":"getCountryView","summary":"Get a country headline snapshot or daily overviews","description":"Without query parameters, returns the current main headline per source plus AI overviews. Pass `at` for a historical UTC moment. Pass `call=daily-overviews` with `from` and `to` for end-of-day AI overviews.","parameters":[{"name":"country","in":"path","required":true,"description":"Country key (lowercase slug).","schema":{"type":"string","enum":["israel","china","finland","france","germany","india","iran","italy","japan","kenya","lebanon","netherlands","palestine","poland","russia","spain","turkey","uk","us","ukraine"],"example":"germany"}},{"name":"call","in":"query","required":false,"description":"Response mode. Defaults to `snapshot`.","schema":{"type":"string","enum":["snapshot","daily-overviews"],"default":"snapshot"}},{"name":"at","in":"query","required":false,"description":"UTC timestamp for a historical snapshot (`call=snapshot` only). ISO 8601, for example `2026-05-01T20:00:00Z`. Omit for the live snapshot.","schema":{"type":"string","format":"date-time","example":"2026-05-01T20:00:00Z"}},{"name":"locale","in":"query","required":false,"description":"Overview language. `heb` is only available when Hebrew overviews exist for that country window.","schema":{"type":"string","enum":["en","heb"],"default":"en"}},{"name":"from","in":"query","required":false,"description":"Range start (`YYYY-MM-DD`). Required when `call=daily-overviews`.","schema":{"type":"string","format":"date","example":"2026-04-29"}},{"name":"to","in":"query","required":false,"description":"Range end (`YYYY-MM-DD`). Required when `call=daily-overviews`. Inclusive. Max span is 7 days.","schema":{"type":"string","format":"date","example":"2026-05-01"}}],"responses":{"200":{"description":"Snapshot or daily-overviews payload.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CountrySnapshot"},{"$ref":"#/components/schemas/DailyOverviewsResponse"}]},"examples":{"snapshot":{"summary":"Live snapshot","value":{"country":"germany","countryName":"Germany","locale":"en","description":"These are the current main headlines from sources across Germany. Headlines refresh every 900 seconds, so they may lag by a few minutes. For context, this response also includes the two latest AI-generated overviews of the headline landscape, plus yesterday's micro-historical overview.","asOfUtc":"2026-05-03T10:00:00.000Z","countryTimezone":"Europe/Berlin","mode":"current-snapshot","headlines":[{"sourceLabel":"Der Spiegel","headline":"Main headline text","subtitle":"Secondary line, may be empty","link":"https://example.com/article","capturedAt":"2026-05-03T09:55:00.000Z"}],"overviews":{"current":{"type":"ai_overview","headline":"Overview headline","summary":"Overview body","capturedAt":"2026-05-03T09:50:00.000Z","period":"current"},"previous":null,"yesterday":{"type":"ai_overview","headline":"Yesterday headline","summary":"Yesterday body","dateLabel":"Daily overview for 2026-05-02","period":"yesterday"}}}},"dailyOverviews":{"summary":"Daily overviews","value":{"country":"germany","countryName":"Germany","locale":"en","call":"daily-overviews","description":"These are AI-generated daily overviews for the headlines from Germany for the requested date range. The overviews were written at the end of each day by an AI model that read the full day's worth of headlines from a full spectrum of sources.","countryTimezone":"Europe/Berlin","from":"2026-04-29","to":"2026-05-01","dailyOverviews":[{"type":"ai_overview","headline":"Day overview headline","summary":"Day overview body","dateLabel":"Daily overview for 2026-04-29"}]}}}}}},"400":{"description":"Invalid country, call, timestamp, or date range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Hebrew overviews are not available for this country window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Failed to build the country snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Headline":{"type":"object","additionalProperties":false,"required":["sourceLabel","headline","subtitle","link","capturedAt"],"properties":{"sourceLabel":{"type":"string"},"headline":{"type":"string"},"subtitle":{"type":"string"},"link":{"type":"string"},"capturedAt":{"type":"string","format":"date-time"}}},"AiOverview":{"type":"object","additionalProperties":false,"required":["type","headline","summary"],"properties":{"type":{"type":"string","const":"ai_overview"},"headline":{"type":"string"},"summary":{"type":"string"},"capturedAt":{"type":["string","null"],"format":"date-time"},"dateLabel":{"type":["string","null"]},"period":{"type":"string","enum":["current","previous","yesterday","requested_day"]}}},"CountrySnapshot":{"type":"object","additionalProperties":false,"required":["country","countryName","locale","description","asOfUtc","countryTimezone","mode","headlines","overviews"],"properties":{"country":{"type":"string","enum":["israel","china","finland","france","germany","india","iran","italy","japan","kenya","lebanon","netherlands","palestine","poland","russia","spain","turkey","uk","us","ukraine"]},"countryName":{"type":"string"},"locale":{"type":"string","enum":["en","heb"]},"description":{"type":"string"},"asOfUtc":{"type":"string","format":"date-time"},"countryTimezone":{"type":["string","null"]},"mode":{"type":"string","enum":["current-snapshot","historical-snapshot"]},"headlines":{"type":"array","items":{"$ref":"#/components/schemas/Headline"}},"overviews":{"type":"object","additionalProperties":false,"required":["current","previous","yesterday"],"properties":{"current":{"oneOf":[{"$ref":"#/components/schemas/AiOverview"},{"type":"null"}]},"previous":{"oneOf":[{"$ref":"#/components/schemas/AiOverview"},{"type":"null"}]},"yesterday":{"oneOf":[{"$ref":"#/components/schemas/AiOverview"},{"type":"null"}]}}}}},"DailyOverviewsResponse":{"type":"object","additionalProperties":false,"required":["country","countryName","locale","call","description","countryTimezone","from","to","dailyOverviews"],"properties":{"country":{"type":"string","enum":["israel","china","finland","france","germany","india","iran","italy","japan","kenya","lebanon","netherlands","palestine","poland","russia","spain","turkey","uk","us","ukraine"]},"countryName":{"type":"string"},"locale":{"type":"string","enum":["en","heb"]},"call":{"type":"string","const":"daily-overviews"},"description":{"type":"string"},"countryTimezone":{"type":["string","null"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"dailyOverviews":{"type":"array","items":{"$ref":"#/components/schemas/AiOverview"}}}},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","resolution"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation of the error."},"resolution":{"type":"string","description":"Concrete guidance for correcting the request or retrying."}}}}}}},"externalDocs":{"description":"Human-readable API documentation","url":"https://www.thehear.org/api"}}