Skip to content
NewsDataHub NewsDataHub API Docs

Filtering Article Results

This page documents all available query parameters for filtering article results on the /news and /top-news endpoints.

q - Search Query

Section titled “q - Search Query”

Use q to compose a search query. Terms support Boolean operators (AND, OR, NOT) and exact phrase matching with quotes. By default, searches across article titles, descriptions, and content. Use the search_in parameter to limit the search scope.

Learn more: Advanced Boolean Search Guide — Complete tutorial on search operators, phrase matching, and complex queries

Examples

Section titled “Examples”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?q=apple%20AND%20banana" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Returns only results where both “apple” and “banana” are present.

search_in - Specify Search Fields

Section titled “search_in - Specify Search Fields”

Control which fields the q parameter searches. Accepts a single value or comma-separated values. Only applies when q is provided; ignored otherwise.

Valid Values

Section titled “Valid Values”
  • all (default) - Search across title, description, and content
  • title - Search only in article titles
  • description - Search only in article descriptions
  • content - Search only in article content

Examples

Section titled “Examples”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?q=election&search_in=title" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Searches only in article titles for “election”.

topic - Filter by Topics

Section titled “topic - Filter by Topics”

Filter by detected topics. Supply repeated parameters (?topic=health&topic=finance) or comma-separated values (?topic=health,finance). If omitted, results span every available topic.

Examples

Section titled “Examples”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?topic=politics" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Returns news tagged as politics.

exclude_topic - Exclude Topics

Section titled “exclude_topic - Exclude Topics”

Exclude one or more topics from the result set. Accepts repeated parameters or comma-separated values, just like topic.

Example

Section titled “Example”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?exclude_topic=sports" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Filters out articles tagged with sports.

language - Filter by Language

Section titled “language - Filter by Language”

Restrict results by language using ISO 639-1 language codes.

Learn more: Multilingual News Tutorial — Access news in 80+ languages with language-specific filtering

Available Languages

Section titled “Available Languages”

en - English, es - Spanish, de - German, fr - French, pt - Portuguese, it - Italian, pl - Polish, ar - Arabic, bg - Bulgarian, ur - Urdu, fa - Persian, el - Greek, ru - Russian, id - Indonesian, nl - Dutch, sv - Swedish, ro - Romanian, sr - Serbian, fi - Finnish, hi - Hindi, ko - Korean, bn - Bengali, zh-cn - Chinese (Simplified), uk - Ukrainian, vi - Vietnamese, mk - Macedonian, hu - Hungarian, tr - Turkish, no - Norwegian, hr - Croatian, bs - Bosnian, ta - Tamil, sq - Albanian, ne - Nepali, ha - Hausa, zh - Chinese, ja - Japanese, he - Hebrew, mr - Marathi, az - Azerbaijani, te - Telugu, kn - Kannada, ml - Malayalam, sl - Slovenian, lt - Lithuanian, sk - Slovak, ms - Malay, et - Estonian, lv - Latvian, hy - Armenian, da - Danish, ca - Catalan, cs - Czech, th - Thai, ky - Kyrgyz, is - Icelandic, km - Khmer, my - Burmese, ka - Georgian, pt-br - Portuguese (Brazil), kk - Kazakh, or - Odia, si - Sinhala, gu - Gujarati, sw - Swahili, as - Assamese, so - Somali, se - Northern Sami, dv - Dhivehi, mn - Mongolian, uz - Uzbek, eu - Basque, rw - Kinyarwanda, be - Belarusian, tl - Tagalog, zu - Zulu, ku - Kurdish, xh - Xhosa, tk - Turkmen, ga - Irish, dz - Dzongkha, kok - Konkani, af - Afrikaans, nn - Norwegian Nynorsk, lb - Luxembourgish, pa - Punjabi, lo - Lao, tet - Tetum

Examples

Section titled “Examples”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?language=fr" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Returns articles published in French.

country - Filter by Country

Section titled “country - Filter by Country”

Filter by source country using comma-separated ISO 3166-1 alpha-2 country codes.

Learn more: Country Filtering Deep Dive — Build geo-targeted feeds and regional monitoring tools

Available Countries

Section titled “Available Countries”

US - United States, GB - United Kingdom, DE - Germany, IN - India, ES - Spain, FR - France, MX - Mexico, CA - Canada, FI - Finland, SE - Sweden, NO - Norway, AU - Australia, BR - Brazil, IT - Italy, NG - Nigeria, GR - Greece, PL - Poland, AR - Argentina, CH - Switzerland, BD - Bangladesh, RO - Romania, IE - Ireland, NL - Netherlands, RU - Russia, PT - Portugal, VE - Venezuela, PH - Philippines, JP - Japan, ZA - South Africa, NP - Nepal, DZ - Algeria, RS - Serbia, BG - Bulgaria, CL - Chile, HU - Hungary, MA - Morocco, AT - Austria, PE - Peru, MK - North Macedonia, LT - Lithuania, PK - Pakistan, UA - Ukraine, AL - Albania, BE - Belgium, LV - Latvia, BA - Bosnia and Herzegovina, IL - Israel, KR - South Korea, SN - Senegal, EE - Estonia, IR - Iran, NZ - New Zealand, UY - Uruguay, LK - Sri Lanka, TH - Thailand, TW - Taiwan, TN - Tunisia, ID - Indonesia, SG - Singapore, IS - Iceland, KZ - Kazakhstan, MR - Mauritania, MY - Malaysia, SK - Slovakia, TR - Turkey, UG - Uganda, AM - Armenia, BY - Belarus, HK - Hong Kong, VN - Vietnam, HR - Croatia, IQ - Iraq, JO - Jordan, SI - Slovenia, SV - El Salvador, AE - United Arab Emirates, BO - Bolivia, GT - Guatemala, HN - Honduras, MD - Moldova, MU - Mauritius, ZW - Zimbabwe, AF - Afghanistan, CM - Cameroon, CO - Colombia, EG - Egypt, GN - Guinea, LB - Lebanon, PA - Panama, SA - Saudi Arabia, SO - Somalia, TZ - Tanzania, GA - Gabon, KE - Kenya, MW - Malawi, ZM - Zambia, AZ - Azerbaijan, CZ - Czech Republic, GH - Ghana, MM - Myanmar, NA - Namibia, PS - Palestine, TG - Togo, BF - Burkina Faso, KG - Kyrgyzstan, KH - Cambodia, SD - Sudan, SY - Syria, GE - Georgia, GY - Guyana, LU - Luxembourg, MZ - Mozambique, RW - Rwanda, YE - Yemen, BB - Barbados, BT - Bhutan, DK - Denmark, HT - Haiti, KN - Saint Kitts and Nevis, LY - Libya, ME - Montenegro, XK - Kosovo, BI - Burundi, BJ - Benin, BW - Botswana, BZ - Belize, CY - Cyprus, DO - Dominican Republic, ML - Mali, NE - Niger, PR - Puerto Rico, SL - Sierra Leone, SR - Suriname, SS - South Sudan, TM - Turkmenistan, UZ - Uzbekistan, AO - Angola, CN - China, FJ - Fiji, JM - Jamaica, MC - Monaco, MG - Madagascar, PY - Paraguay, BH - Bahrain, BS - Bahamas, CR - Costa Rica, CU - Cuba, EC - Ecuador, ER - Eritrea, GD - Grenada, GM - Gambia, LR - Liberia, NI - Nicaragua, OM - Oman, PG - Papua New Guinea, VC - Saint Vincent and the Grenadines, AD - Andorra, AW - Aruba, BM - Bermuda, ET - Ethiopia, LC - Saint Lucia, PW - Palau, SB - Solomon Islands, TD - Chad, AG - Antigua and Barbuda, AS - American Samoa, CF - Central African Republic, CG - Republic of the Congo, CI - Ivory Coast, EU - European Union, IM - Isle of Man, KW - Kuwait, LA - Laos, MN - Mongolia, MV - Maldives, SC - Seychelles, TJ - Tajikistan, TT - Trinidad and Tobago, VA - Vatican City, VG - British Virgin Islands, VI - U.S. Virgin Islands, GI - Gibraltar, GQ - Equatorial Guinea, GU - Guam, JE - Jersey, LI - Liechtenstein, LS - Lesotho, MP - Northern Mariana Islands, MT - Malta, NC - New Caledonia, QA - Qatar, RE - Réunion, SM - San Marino, ST - São Tomé and Príncipe, TL - Timor-Leste, TO - Tonga, WS - Samoa

Examples

Section titled “Examples”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?country=US" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Returns articles from United States sources.

source - Filter by Source Name

Section titled “source - Filter by Source Name”

Filter by source name (case sensitive). Supports repeated parameters or comma-separated values.

Example

Section titled “Example”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?source=CryptoPotato" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Returns all available articles for CryptoPotato.

exclude_source - Exclude Sources

Section titled “exclude_source - Exclude Sources”

Exclude specific sources from results. Accepts repeated parameters or comma-separated values, just like source.

Example

Section titled “Example”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?exclude_source=NewsBytes,Nasdaq" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Filters out articles from NewsBytes and Nasdaq.

political_leaning - Filter by Political Leaning

Section titled “political_leaning - Filter by Political Leaning”

Restrict sources by political leaning classification. Accepts repeated parameters or comma-separated values. Valid options: left, center_left, center, center_right, right, far_left, far_right.

Learn more: Political Leaning Filter Guide — Build balanced feeds and compare coverage across the political spectrum

Example

Section titled “Example”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?political_leaning=center,center_left" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Limits results to sources grouped as center or center-left.

source_type - Filter by Source Type

Section titled “source_type - Filter by Source Type”

Filter by publication type. Accepts repeated parameters or comma-separated values.

Learn more: Source Type Filter Guide — Target newspapers, magazines, digital-native outlets, press releases, and more

Available Source Types

Section titled “Available Source Types”
  • digital_native - News organizations that originated online and primarily publish digitally
  • press_release - Official announcements issued by organizations
  • newspaper - Traditional print news publications, including their online versions
  • magazine - Periodical publications covering specific subjects or interests
  • mainstream_news - Major news outlets with broad audience reach
  • blog - Regularly updated websites typically run by individuals or small groups
  • specialty_news - Publications focused on specific industries, topics, or niches
  • news_agency - Wire services and news agencies that distribute content to other outlets

Examples

Section titled “Examples”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?source_type=mainstream_news" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Returns articles published by mainstream outlets only.

fields - Select Response Fields

Section titled “fields - Select Response Fields”

Request a subset of response fields. Provide a comma-separated list (for example, title,pub_date,source_title). The id field is always included.

Learn more: Fields Parameter Optimization — Reduce bandwidth and improve performance by requesting only the fields you need

Example

Section titled “Example”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?fields=title,pub_date,article_link" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Returns only identifiers, titles, publication dates, and links.

per_page - Control Page Size

Section titled “per_page - Control Page Size”

Control page size. All tiers support up to 100 results per page. Default values vary by tier (Free: 10, Paid: 50).

Example

Section titled “Example”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?per_page=100" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Requests 100 results per page (available to all tiers).

start_date & end_date - Filter by Date

Section titled “start_date & end_date - Filter by Date”

Filter by publication date using ISO 8601 (YYYY-MM-DD).

Examples

Section titled “Examples”
Terminal window
curl -X GET "https://api.newsdatahub.com/v1/news?start_date=2025-01-01&end_date=2025-01-05" \
  -H "X-Api-Key: your_api_key_here" \
  -H "User-Agent: docs-filtering-articles/1.0-curl"

Returns articles published between 1-5 January 2025.

cursor - Pagination

Section titled “cursor - Pagination”

Paginate through results by passing the next_cursor value from the previous response.

Example

Section titled “Example”
https://api.newsdatahub.com/v1/news?cursor=eyJvZmZzZXQiOjIwLCJ0aW1lc3RhbXAiOiIyMDI1LTAxLTE1VDEwOjMwOjAwWiJ9

Retrieves the next page of results.