SocialCrawl

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:

PlatformWhere the country comes fromgeo.country.source
TikTokThe video's own countrypost_region
XThe location the author gives on their profile, such as "Halifax, Nova Scotia"author_location
RedditA subreddit named for a place, such as r/PersonalFinanceCanadacommunity
News and web pagesThe publisher's country domain, such as cbc.capublisher_domain
YouTube, Instagram, FacebookThe author's declared country, with include=author_countryauthor_declared, author_about, profile_address
Amazon, Walmart, eBayThe store the listing was searched onmarketplace
Any platformA city, province or country named in the postcaption_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
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.

TypeScript
// 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

Terminal
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: 4

That 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 platforms with include=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,US keeps rows from either. exclude_country drops the countries you name and keeps the rest.
  • One run per region: a POST takes groups, each with its own country, languages and keywords.
  • Recent posts only: add period=90d, or since with a date.