# Discover rows from one country (/docs/recipes/discover-rows-by-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` |
| Reddit | 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

```bash title="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 title="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

```text title="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.

## Related

- [Discover](/docs/prism/discover.md): Every parameter, including country, languages and include.
- [Instagram reels from one market](/docs/recipes/instagram-reels-by-market.md): Reels by creators based in one country.
- [Accounts behind a topic](/docs/recipes/accounts-behind-a-topic.md): The accounts posting about a topic, with their profiles.