Discover rows from one country
Search several platforms for a topic and keep only the posts from one country, in each of its languages. 1 credit per platform search, plus 1 per author when you look up YouTube, Instagram or Facebook authors.
You will run one Discover search across X, Reddit and news and get back only posts placed in one country, in each of its languages. The example finds Canadian posts about mortgage renewal in English and French.
Cost: each platform search is 1 credit. The TypeScript example below ran four searches and cost 4 credits on 29/10/2026. Looking up YouTube, Instagram or Facebook authors adds 1 credit per author.
How does Discover know where a post is from?
Each row carries geo.country, and geo.country.source says where the country came from:
| Platform | Where the country comes from | geo.country.source |
|---|---|---|
| TikTok | The video's own country | post_region |
| X | The location the author gives on their profile, such as "Halifax, Nova Scotia" | author_location |
| A subreddit named for a place, such as r/PersonalFinanceCanada | community | |
| News and web pages | The publisher's country domain, such as cbc.ca | publisher_domain |
| YouTube, Instagram, Facebook | The author's declared country, with include=author_country | author_declared, author_about, profile_address |
| Amazon, Walmart, eBay | The store the listing was searched on | marketplace |
| Any platform | A city, province or country named in the post | caption_text |
country=CA drops rows placed in another country. A row with no country is kept unless you also send unknown_country=drop.
Step 1: keep only rows placed in one country
curl "https://www.socialcrawl.dev/v1/prism/discover?keywords=mortgage%20renewal&platforms=reddit,twitter,news&country=CA&unknown_country=drop&limit=50" \
-H "x-api-key: YOUR_API_KEY"On 29/10/2026 this kept 56 rows, every one placed in Canada, and dropped 39 rows with no country and 2 from other countries. summary.geo.fill_rate is the share of kept rows that carry a country.
Step 2: every language spoken there
Send the keyword in each language, the way people there write it, and list the languages in languages. With country, the news is searched once per language, at 1 credit a search.
// discover-rows-by-country.ts
// Canadian posts about mortgage renewal, in English and French.
// Run with: SOCIALCRAWL_KEY=sc_... npx tsx discover-rows-by-country.ts
const KEY = process.env.SOCIALCRAWL_KEY;
if (!KEY) throw new Error("Set SOCIALCRAWL_KEY");
const BASE = "https://www.socialcrawl.dev/v1";
const url = new URL(`${BASE}/prism/discover`);
url.searchParams.set("keywords", "mortgage renewal,renouvellement hypothécaire");
url.searchParams.set("platforms", "reddit,twitter,news");
url.searchParams.set("country", "CA");
url.searchParams.set("languages", "en,fr");
url.searchParams.set("limit", "50");
const res = await fetch(url, { headers: { "x-api-key": KEY } });
const json = (await res.json()) as {
success: boolean;
credits_used: number;
data: {
summary: { geo: { fill_rate: number } };
items: Array<{
platform: string;
url: string;
language: string | null;
geo: { country: { value: string; source: string } | null };
}>;
};
error?: { message: string };
};
if (!json.success) throw new Error(json.error?.message ?? "discover failed");
const { summary, items } = json.data;
const byLanguage: Record<string, number> = {};
for (const row of items) {
const lang = row.language ?? "unknown";
byLanguage[lang] = (byLanguage[lang] ?? 0) + 1;
}
console.log(`rows: ${items.length}, by language: ${JSON.stringify(byLanguage)}`);
console.log(`kept rows with a country: ${Math.round(summary.geo.fill_rate * 100)}%`);
for (const row of items.slice(0, 3)) {
console.log(
`${row.platform} ${row.language} ${row.geo.country?.value} (${row.geo.country?.source}) ${row.url}`,
);
}
console.log(`credits used: ${json.credits_used}`);What you get back
rows: 50, by language: {"en":24,"fr":25,"unknown":1}
kept rows with a country: 62%
reddit en CA (community) https://www.reddit.com/r/PersonalFinanceCanada/comments/1vymv47/...
twitter en CA (author_location) https://x.com/wealthmoose/status/2115580720366207028
news en CA (publisher_domain) https://www.ratehub.ca/blog/renewing-your-mortgage-in-2026-heres-what-to-expect/
(47 more rows)
credits used: 4That run, on 29/10/2026, returned 50 rows, all placed in Canada; the French ones include posts in r/QuebecFinance and stories on 985fm.ca. A news language the country's edition does not carry is skipped and named in data._warnings, and a run searches the news in at most 4 languages per country.
What to change
- YouTube, Instagram and Facebook: add them to
platformswithinclude=author_country, which looks up each author's declared country at 1 credit per author. Channels that declare no country stay unknown. - Several countries:
country=CA,USkeeps rows from either.exclude_countrydrops the countries you name and keeps the rest. - One run per region: a
POSTtakesgroups, each with its owncountry,languagesand keywords. - Recent posts only: add
period=90d, orsincewith a date.
