News article schema
The unified SocialCrawl news article schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.
News article schema
Every SocialCrawl endpoint that returns a news article gives you this exact shape, whatever the source platform. Write your parser once and the same code reads news article data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats.
Field reference
| Field | Type | Nullable | Description |
|---|---|---|---|
id | string | No | Stable article ID (hash of the url) |
title | string | Yes | Article headline |
url | string | Yes | Direct URL to the article |
source | string | Yes | Publishing outlet name (falls back to the domain) |
domain | string | Yes | Host domain of the article |
snippet | string | Yes | Article excerpt (news_search items only; null on top_stories) |
image_url | string | Yes | Thumbnail image URL |
published_at | string or integer | Yes | Absolute UTC publish time |
rank | integer | Yes | Result rank (news_search items only; null on top_stories) |
placement | string | Yes | Source list: "news_search" or "top_stories" |
Platform availability
1 platform return the News article shape. id are never null on any platform. The fields below vary: yes means the platform populates it (the value may still be null); a blank means the platform never provides it, so it is always null.
| Platform | title | url | source | domain | snippet | image_url | published_at | rank | placement |
|---|---|---|---|---|---|---|---|---|---|
| Google News | yes | yes | yes | yes | yes | yes | yes | yes |
Machine-readable schema
Validate responses programmatically against the JSON Schema (2020-12):
Point a validator (Ajv, jsonschema, or your framework's) at that URL, or hand it to an agent so it can check the shape without a live call.
Returned by
Endpoints with the NewsArticleList archetype return this shape:
See how the same fields map to each platform's raw upstream names in the cross-platform field equivalence table.