Skip to main content
POST
/
api
/
search_by
Search articles by identifiers
curl --request POST \
  --url https://local-news.newscatcherapi.com/api/search_by \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: <api-key>' \
  --data '{
  "links": "https://nytimes.com/article1",
  "ids": [
    "5f8d0d55b6e45e00179c6e7e",
    "5f8d0d55b6e45e00179c6e7f"
  ],
  "rss_guids": [
    "https://example.com/article1",
    "https://example.com/article2"
  ],
  "from_": "2024/09/24",
  "to_": "2024/09/25",
  "page": 2,
  "page_size": 100
}'
{
  "status": "ok",
  "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
​
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.

Note: You can use the links parameter in combination with ids or rss_guids, but at least one of these parameters must be provided.

Example:

"https://nytimes.com/article1"

​
ids

The Newscatcher article ID (see 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.

Note: You can use the ids parameter in combination with links or rss_guids, but at least one of these parameters must be provided.

Example:
[
  "5f8d0d55b6e45e00179c6e7e",
  "5f8d0d55b6e45e00179c6e7f"
]
​
rss_guids

The RSS GUID (Globally Unique Identifier) or list of GUIDs to search for. To specify multiple GUIDs, use a comma-separated string or an array of strings.

GUIDs are unique identifiers assigned to RSS feed items. They are often URLs or other unique strings.

Note: You can use the rss_guids parameter in combination with links or ids, but at least one of these parameters must be provided.

Example:
[
  "https://example.com/article1",
  "https://example.com/article2"
]
​
from_
default:7 days 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-09-24T00:00:00
  • YYYY-MM-dd: 2024-09-24
  • YYYY/mm/dd HH:MM:SS: 2024/09/24 00:00:00
  • YYYY/mm/dd: 2024/09/24
  • English phrases: 1 day ago, today

Note: By default, applied to the publication date of the article. To use the article's parse date instead, set the by_parse_date parameter to true.

Example:

"2024-09-24T00:00:00.000Z"

​
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-09-25T00:00:00
  • YYYY-MM-dd: 2024-09-25
  • YYYY/mm/dd HH:MM:SS: 2024/09/25 00:00:00
  • YYYY/mm/dd: 2024/09/25
  • English phrases: 1 day ago, today, now

Note: By default, applied to the publication date of the article. To use the article's parse date instead, set the by_parse_date parameter to true.

Example:

"2024-09-25T00:00:00.000Z"

​
page
integer
default:1

The page number to scroll through the results. This parameter is used to paginate: scroll through results because one API response cannot return more than 1000 articles.

Required range: x >= 1
Example:

2

​
page_size
integer
default:100

The number of articles to return per page. Range: 1 to 1000.

Required range: 1 <= x <= 1000
Example:

100

Response

A successful response containing articles that match the specified search criteria.

The response model for the Search advanced, Latest headlines advanced, and Search by requests.

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.).
​
status
string
default:ok
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
Article Result (Advanced) · object[]
​
user_input
object