Search articles by links or IDs

POST

api

search_by_link

curl --request POST \
  --url https://v3-api.newscatcherapi.com/api/search_by_link \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: <api-key>' \
  --data '{
  "ids": [
    "8ea8a784568ffaa05cb6d1ab2d2e84dd",
    "0146a551ef05ab1c494a55e806e3ce64"
  ],
  "links": [
    "https://www.nytimes.com/2024/08/30/technology/ai-chatbot-chatgpt-manipulation.html",
    "https://www.bbc.com/news/articles/c39k379grzlo"
  ]
}'

{
  "status": "<string>",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "articles": [],
  "user_input": {}
}

Authorizations

x-api-token

string

header

required

API Key to authenticate requests.

To access the API, include your API key in the x-api-token header. To obtain your API key, complete the form or contact us directly.

Body

application/json

Request body for searching articles based on specified links or IDs.

ids

The Newscatcher article ID (corresponds to the _id field in API response) or a list of article IDs to search for. To specify multiple IDs, use a comma-separated string or an array of strings.

Examples:

"5f8d0d55b6e45e00179c6e7e,5f8d0d55b6e45e00179c6e7f"
["5f8d0d55b6e45e00179c6e7e","5f8d0d55b6e45e00179c6e7f"]

Caution: You can use either the links or the ids parameter, but not both at the same time.

Example:

[
  "5f8d0d55b6e45e00179c6e7e",
  "5f8d0d55b6e45e00179c6e7f"
]

links

The article link or list of article links to search for. To specify multiple links, use a comma-separated string or an array of strings.

Examples:

"https://nytimes.com/article1, https://bbc.com/article2"
["https://nytimes.com/article1", "https://bbc.com/article2"]

Caution: You can use either the links or the ids parameter, but not both at the same time.

Example:

"https://nytimes.com/article1"

from_

default:1 month ago

The starting point in time to search from. Accepts date-time strings in ISO 8601 format and plain text strings. The default time zone is UTC.

Formats with examples:

YYYY-mm-ddTHH:MM:SS: 2024-07-01T00:00:00
YYYY-MM-dd: 2024-07-01
YYYY/mm/dd HH:MM:SS: 2024/07/01 00:00:00
YYYY/mm/dd: 2024/07/01
English phrases: 1 day ago, today

Example:

"2021/01/01"

to_

default:now

The ending point in time to search up to. Accepts date-time strings in ISO 8601 format and plain text strings. The default time zone is UTC.

Formats with examples:

YYYY-mm-ddTHH:MM:SS: 2024-07-01T00:00:00
YYYY-MM-dd: 2024-07-01
YYYY/mm/dd HH:MM:SS: 2024/07/01 00:00:00
YYYY/mm/dd: 2024/07/01
English phrases: 1 day ago, today

Example:

"2021/12/31"

page

integer

default:1

The page number to scroll through the results. Use for pagination, as a single API response can return up to 1,000 articles.

For details, see How to paginate large datasets.

Required range: x >= 1

Example:

2

page_size

integer

default:100

The number of articles to return per page.

Required range: 1 <= x <= 1000

Example:

50

Response

200

application/json

A successful response containing articles that match the provided links or IDs.

The response model for the search requests applies to the Search, Latest Headlines, Search by link, and Authors endpoints. Response field behavior:

Required fields are guaranteed to be present and non-null.
Optional fields may be null/undefined if the data couldn't be extracted during processing.
To access article properties in the articles response array, use array index notation. For example, articles[n].title, where n is the zero-based index of the article object (0, 1, 2, etc.).
The nlp property within the article object articles[n].nlp is only available with NLP-enabled subscription plans.

status

string

required

The status of the response.

total_hits

integer

required

The total number of articles matching the search criteria.

page

integer

required

The current page number of the results.

total_pages

integer

required

The total number of pages available for the given search criteria.

page_size

integer

required

The number of articles per page.

articles

object[]

A list of articles matching the search criteria.

The data model representing a single article in the search results.

articles.title

string

required

The title of the article.

articles.link

string

required

The URL link to the article.

articles.domain_url

string

required

The domain URL of the article.

articles.full_domain_url

string

required

The full domain URL of the article.

articles.parent_url

string

required

The categorical URL of the article.

articles.rank

integer

required

The rank of the article's source.

articles.content

string

required

The content of the article.

articles.id

string

required

The unique identifier for the article.

articles.score

number

required

The relevance score of the article.

articles.author

string

The primary author of the article.

articles.authors

A list of authors of the article.

articles.journalists

A list of journalists associated with the article.

articles.published_date

string

The date the article was published.

articles.published_date_precision

string

The precision of the published date.

articles.updated_date

string

The date the article was last updated.

articles.updated_date_precision

string

The precision of the updated date.

articles.parse_date

string

The date the article was parsed.

articles.name_source

string

The name of the source where the article was published.

articles.is_headline

boolean

Indicates if the article is a headline.

articles.paid_content

boolean

Indicates if the article is paid content.

articles.country

string

The country where the article was published.

articles.rights

string

The rights information for the article.

articles.media

string

The media associated with the article.

articles.language

string

The language in which the article is written.

articles.description

string

A brief description of the article.

articles.word_count

integer

default:0

The word count of the article.

articles.is_opinion

boolean

Indicates if the article is an opinion piece.

articles.twitter_account

string

The Twitter account associated with the article.

articles.all_links

A list of all URLs mentioned in the article.

articles.all_domain_links

A list of all domain URLs mentioned in the article.

articles.nlp

object

Natural Language Processing data for the article.

articles.nlp.theme

string

The themes or categories identified in the article.

articles.nlp.summary

string

A brief AI-generated summary of the article content.

articles.nlp.sentiment

object

Sentiment scores for the article's title and content.

articles.nlp.new_embedding

number[]

A dense 1024-dimensional vector representation of the article content, generated using the multilingual-e5-large model.

Note: The new_embedding field is only available in the v3_local_news_nlp_embeddings subscription plan.

articles.nlp.ner_PER

object[]

Named Entity Recognition for person entities (individuals' names).

articles.nlp.ner_ORG

object[]

Named Entity Recognition for organization entities (company names, institutions).

articles.nlp.ner_MISC

object[]

Named Entity Recognition for miscellaneous entities (events, nationalities, products).

articles.nlp.ner_LOC

object[]

Named Entity Recognition for location entities (cities, countries, geographic features).

articles.nlp.iptc_tags_name

string[]

IPTC media topic taxonomy paths identified in the article content. Each path represents a hierarchical category following the IPTC standard.

articles.nlp.iptc_tags_id

string[]

IPTC media topic numeric codes identified in the article content. These codes correspond to the standardized IPTC media topic taxonomy.

articles.nlp.iab_tags_name

string[]

IAB content taxonomy paths identified in the article content. Each path represents a hierarchical category following the IAB content standard.

articles.custom_tags

object

An object that contains custom tags associated with an article, where each key is a taxonomy name, and the value is an array of tags.

articles.additional_domain_info

object

Additional information about the domain of the article.

Example:

{
  "is_news_domain": true,
  "news_type": "News and Blogs",
  "news_domain_type": "Original Content"
}

user_input

object

The user input parameters for the request.

Was this page helpful?

Suggest edits Raise issue

Search articles by links or IDs Search similar articles

curl --request POST \
  --url https://v3-api.newscatcherapi.com/api/search_by_link \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: <api-key>' \
  --data '{
  "ids": [
    "8ea8a784568ffaa05cb6d1ab2d2e84dd",
    "0146a551ef05ab1c494a55e806e3ce64"
  ],
  "links": [
    "https://www.nytimes.com/2024/08/30/technology/ai-chatbot-chatgpt-manipulation.html",
    "https://www.bbc.com/news/articles/c39k379grzlo"
  ]
}'

{
  "status": "<string>",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "articles": [],
  "user_input": {}
}

Overview

Endpoints

Libraries

Search articles by links or IDs

Authorizations

Body

Response