SocialCrawl
Scrape

Filter by country and language

See what country and region do on each platform, and where a row's country comes from

A parameter named country or region changes what a call returns, but not always in the same way. This page says which job it does on each kind of endpoint, and how SocialCrawl decides which country a row belongs to.

What do country and region do?

A parameter named country or region does one of three jobs. The name does not tell you which, so read the parameter's line on the endpoint before you send it.

JobWhat it doesWhere you meet it
Picks a store or marketThe platform keeps a separate catalog for each market, and the parameter chooses one. Listings, prices and currency follow it.country on Amazon, eBay and the App Store. region on TikTok Shop and Klarna.
Sets where the request is made fromThe platform answers as it would for a reader in that country. Rows from other countries still come back.region on TikTok search and profile videos, and on YouTube search.
Keeps only rows from that countryRows that belong to another country are dropped from the page.country on TikTok search, Instagram reel search and Discover.

TikTok search takes both. region sets where the request is made from and does not filter the page. country keeps only the videos TikTok registers to the countries you name.

A filter can cost more than the plain page. Instagram reel search prices country by the creators it looks up, so read its line before you send it.

To know where a row is from, read the country on the row itself, such as post.ext.region on a TikTok video. Each platform page lists its endpoints that take country or region, under its endpoint table, with what the parameter does there.

Keep only rows from a country in Discover

Discover takes country and keeps only the rows it can place in that country. Price a run for free first:

cURL
curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: sc_your_key_here" \
  --data-urlencode "query=sunscreen" \
  --data-urlencode "country=KR" \
  --data-urlencode "period=30d" \
  --data-urlencode "dry_run=true"

exclude_country drops rows from the countries you name, and unknown_country decides whether a row with no country is kept.

Where a row's country comes from

geo.country.source names how the country was found: post_region, post_geotag, author_declared, author_about, profile_address, author_location (the location an X author typed on their profile, read with country, state and province names, so "Halifax, Nova Scotia" and "London, ON" are Canada), community (a subreddit named for a place, such as r/PersonalFinanceCanada or r/QuebecFinance), marketplace (the store a listing was searched on, such as amazon.ca), publisher_domain (a news or web publisher's country domain, such as cbc.ca), phone_prefix, currency, caption_text, website_cctld or language. geo.country.confidence goes from 0 to 1, and country, exclude_country and unknown_country count a country only at 0.3 or more; a guess from the language or a price is shown on the row and filtered as unknown. A country from caption_text comes from place names in the text, matched against a gazetteer built from GeoNames data, used under the Creative Commons Attribution 4.0 license (CC BY 4.0), and from CLDR country names. geo.missing says why a row has no country, one source:reason per source tried. For the author's own country it is author_declared:needs_author_join when include=author_country would look the author up, author_declared:not_set_by_author when the lookup ran and the profile sets no country, author_declared:author_unavailable when the platform serves no such account or not publicly, and author_declared:no_author when the row names no author to look up.

Where each platform's country comes from

The country is read by code from what the account itself publishes, never guessed from the language of its posts.

  • Instagram: the About page of the account.
  • YouTube: the channel's country.
  • Facebook pages: the address on the page, so "Dubai" or "Deira, Dubai, United Arab Emirates" gives the UAE.
  • X: the location text on the profile. Before the profile is looked up, the same text on the account's posts gives a hinted country (source: "author_location"), which a declared country replaces.
  • LinkedIn: the member's location.
  • Reddit and Telegram: no location field, so only the bio, a phone prefix or a website domain can give a hint.

An account whose text names no single country has no country, and unknown_country decides whether it is kept.

An account is a mentioned account (evidence[].kind: "mentioned") only on a platform your run searched. A shop domain or a handle named in a post on a platform you did not list in platforms is not returned and is not looked up.

Next steps