API docsUser guidesChangelogFree TrialSupportContact sales
User guides
Sign In

Using News search parameters

Search Terms
You can search for news content using free text search terms. Passing search terms in double quotes, such as "Tree planting", will perform an exact search term match.

Article Publication Date Range
To search for articles using the article publication date range, use the start_date and end_date parameters. These date ranges are the most commonly used date parameters in the API.

  • start _date The oldest article publication date to search from, in the format YYYY-MM-DD. Default is one month from today's date. The maximum date range size is one year. The earliest possible start_date is 2018-09-24.

  • end_date The most recent article publication date to search to in the format YYYY-MM-DD. Default is today's date. The maximum date range size is one year.

Article Database Added Date Range
Keeping your systems up to date with real time news is important to many of our developers and clients. So that you can stay in sync with the Candid News database, which is updated as frequently as every 15 minutes, we offer the ability to search by the date and time an article was inserted into the database. To do so, you can call the API by passing an added_start_date and added_end_date parameters, with an added_end_date 15 minutes later than added_start_date. If you call the API every 15 minutes, you’ll pick up all new articles across all possible number of API result pages. If you do not require real-time news, you can expand the range to daily, weekly, or a time range that best fits your processes.

  • added_state_date Used to search by the earliest date an article was added to Candid News database, in the format yyyy-MM-dd'T'HH:mm:ss.SSSXXX. Default is one month from today's date. The maximum date window size is one year. The earliest date to search from is 2018-09-24.

  • added_end_date Used to search by most recent date and time article was added to the Candid News database, in the format yyyy-MM-dd'T'HH:mm:ss.SSSXXX. Default is today's date. The maximum date window size is one year.

EINs and Organization Names
There are two ways to search for news content on specific organizations.

  1. Using the EINs for the organizations you are interested in. EINs can be formatted with or without a dash. This is a direct way to search for organizations, as Candid performs a process to identify distinct organizations within content and match content to an organization's EIN. This process applies to articles published starting in late 2020, so use the organization name to search for content published prior to late 2020. To search for content related to organizations before late 2020 instead use the organization name. You can pass up to 25 EINs at a time, which will be joined using OR.
  2. Using the names of the organizations you are interested in. This is a broader way of searching for organizations. You can pass up to 25 organization names at a time that will be joined using OR.

Locations with GeoName ID
The locations search in the Candid News API uses GeoNames, which is a user-editable geographical database available through various web services under a Creative Commons attribution license.

A GeoName ID is required to search locations using the Candid News API. Please refer to Candid's geo search for more information.

Subjects and Populations with Candid's Philanthropy Classification System (PCS)
A valuable way to search for news is to use Candid's Philanthropy Classification System (PCS), which is Candid's taxonomy describing subjects and populations in the social sector.

To deploy the PCS in your system, you will need to use the codes associated to each term for relevant searches in the Candid News API. Please refer to Candid's taxonomy for more information.

People
Search using the names of people mentioned in news content. You can pass up to 25 people names at a time, which will be joined using OR.

Sources Include & Sources Exclude
Search by including or excluding specific news sources in URL format. By default, leaving these parameters blank will search across all news sources. You can pass up to 25 sources at a time that will be joined using OR.

Ask your sales representative for a seed file of our top 5,000 news sources.

Staff Change Mentioned
Search for news content containing mentions of staff changes, which are topics such as promotions, retirements, and new hires. True = Only return articles containing mentions of staff changes. False = Do not return articles containing mentions of staff changes. Null = Return articles regardless of staff changes mentioned.

RFP Mentioned
Search for news content containing mentions of RFPs. True = Only return articles containing mentions of RFPs. False = Do not return articles containing mentions of RFPs. Null = Return articles regardless of RFPs mentioned.

Grant Mentioned
Search for news content containing mentions of grants. True = Only return articles containing mentions of grants. False = Do not return articles containing mentions of grants. Null = Return articles regardless of grants mentioned.

Advisory Content
Advisory content is flagged for organizations or people in the social sector that may or may not require due diligence. True = Only return articles flagged as advisory content. False = Do not return articles flagged as advisory content. Null = Return articles regardless of advisory content.

AND/OR Filter Operator
Toggle the and/or union type for searches for the following parameters Subjects, Populations, Locations, People, and Organizations. Default is AND. Please note that inter-array parameter values are not affected by the filter operator.

Updated almost 3 years ago