Home › API documentation › Response fields

Response fields

What every field means, how reliable it is, and where it came from. Coverage percentages are measured against the live corpus, not estimated.

Field	Type	Coverage	Meaning
`id`	string	100%	Stable identifier, the MD5 of the URL. Same article, same id, forever.
`url`	string	100%	Canonical article URL at the publisher. Always present — attribute back to it.
`title`	string	100%	Headline, taken from the article markup rather than the page title where possible.
`description`	string	98%	Standfirst or summary, from JSON-LD, `og:description` or the meta description, in that order of preference.
`text`	string	100%	Full article body, boilerplate stripped. Only returned with `full_text=true`. Typically 2,000–4,000 characters.
`published_at`	ISO 8601 UTC	100%	Publication time. Exact to the minute for 84% of articles; the rest fall back to the crawl date. See `date_source`.
`date_source`	enum	100%	Where the date came from: `jsonld`, `meta`, `extracted`, `crawled` or `crawled_clamped`.
`crawled_at`	ISO 8601 UTC	100%	When the page was crawled into our sources. Never backdated, so it is the honest field to sort by when polling for new material.
`host`	string	100%	Hostname from the URL, lowercase, including any `www.` prefix.
`sitename`	string	91%	Publication name as the publisher states it, e.g. The Guardian.
`country`	ISO 3166-1 alpha-2	85%	Publisher country, inferred. Read `country_source` before trusting it.
`country_source`	enum	100%	How the country was determined. See the table below.
`lang`	ISO 639-1	99.9%	Article language as the publisher declares it. Wrong on multilingual sites that serve every edition under one locale — see quality.
`tld`	string	100%	Top-level domain without the dot. A fact, unlike `country`.
`author`	string	46%	Byline where the publisher marks one up. Frequently absent or an agency name.
`categories`	string[]	38%	Publisher's own section labels. Not normalised across publishers — treat as a hint, not a taxonomy.
`image`	string	88%	Lead image URL, from `og:image` or JSON-LD. Hotlinks to the publisher.
`score`	float	—	Relevance score. Present only with `sort=relevance`. Comparable within one response, meaningless across responses.
`highlight`	object	—	Matched fragments with `<em>` tags. Present only with `highlight=true`.

country_source — how much to trust the country

No competitor publishes this. We do, because roughly a third of the values are inferences rather than facts, and an agent building an analysis on top deserves to know which is which.

Value	Reliability	How it was derived
`cctld`	high	Country-code top-level domain: `.ua` → UA. Essentially always right.
`publisher`	high	The publisher's own `addressCountry` in JSON-LD organisation markup.
`og_locale`	good	Region subtag of `og:locale`, e.g. `pt_BR` → BR.
`html_lang`	good	Region subtag of `<html lang>`, e.g. `de-AT` → AT.
`jsonld_lang`	good	Region subtag of the article's `inLanguage`.
`lang`	weak	Guessed from language alone where a language maps to one dominant country.
`weak_en_us`	unreliable	`en-US` shipped as a template default. Common on Indian, Nigerian and Filipino sites. Exclude with `strict_country=true`.
`unknown`	—	No usable signal. The `country` field is absent.

date_source — how much to trust the timestamp

Value	Share	Meaning
`jsonld`	86%	`datePublished` from schema.org markup. Exact.
`extracted`	9%	Parsed from the page body or URL. Usually exact to the day.
`meta`	4%	From an `article:published_time` meta tag.
`crawled`	<1%	No date found; crawl time substituted. Accurate to within hours.
`crawled_clamped`	<1%	The publisher declared a future date, so it was clamped to crawl time. Without this, one mislabelled article would sit at the top of every date-sorted query.