Search for events

POST

api

events_search

curl --request POST \
  --url https://events.newscatcherapi.xyz/api/events_search \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: <api-key>' \
  --data '{
  "event_type": "layoff",
  "attach_articles_data": false,
  "additional_filters": {
    "company_name": "<string>",
    "event_date": {
      "gte": "<string>",
      "lte": "<string>"
    },
    "extraction_date": {
      "gte": "<string>",
      "lte": "<string>"
    },
    "layoff.how_much_related": "Completely Irrelevant",
    "layoff.is_relevant_for_real_estate": "true",
    "layoff.layoff_reason": "<string>",
    "layoff.location": {
      "country": "<string>",
      "city": "<string>",
      "raw_location": "<string>",
      "county": "<string>",
      "state": "<string>"
    },
    "layoff.max_number_of_people_laid_off": {
      "gte": 123,
      "lte": 123
    },
    "layoff.min_number_of_people_laid_off": {
      "gte": 123,
      "lte": 123
    },
    "layoff.number_of_people_laid_off": {
      "gte": 123,
      "lte": 123
    },
    "layoff.percentage_of_people_laid_off": {
      "gte": 123,
      "lte": 123
    },
    "layoff.summary": "<string>"
  },
  "additional_article_fields": [
    "description",
    "published_date",
    "nlp.summary"
  ]
}'

{
  "message": "Success",
  "count": 25,
  "events": [
    {
      "id": "n1jk-pQBvyT_ytpRpzBn",
      "event_type": "layoff",
      "global_event_type": "Layoff",
      "associated_article_ids": [
        "<string>"
      ],
      "extraction_date": "2023-11-07T05:31:56Z",
      "event_date": "2023-11-07T05:31:56Z",
      "articles": [
        {
          "id": "<string>",
          "title": "<string>",
          "link": "<string>",
          "media": "<string>"
        }
      ],
      "company_name": "<string>",
      "layoff": {
        "summary": "<string>",
        "layoff_reason": "<string>",
        "max_number_of_people_laid_off": 123,
        "min_number_of_people_laid_off": 123,
        "number_of_people_laid_off": 123,
        "percentage_of_people_laid_off": 123,
        "how_much_related": "Completely Irrelevant",
        "is_relevant_for_real_estate": true,
        "location": [
          {
            "country": "<string>",
            "city": "<string>",
            "raw_location": "<string>",
            "county": "<string>",
            "state": "<string>"
          }
        ]
      }
    }
  ]
}

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

Parameters for searching events.

event_type

enum<string>

required

The type of events to retrieve from the database.

Available options:

layoff,

data_breach,

fundraising

attach_articles_data

boolean

default:

false

If true, includes source article data in the response. If false, returns only event data.

additional_filters

object

The event-specific filtering parameters. Required structure depends on the event_type value.

additional_filters.company_name

string

The name of the company that conducted or is conducting the layoffs.

additional_filters.event_date

object

The date when the layoff occurred. Accepts both absolute dates (YYYY-MM-DD) and relative dates (e.g., "now", "now-30d"). Default: Last 30 days.

additional_filters.extraction_date

object

The date when the event was extracted from news sources. Accepts both absolute dates (YYYY-MM-DD) and relative dates.

The relevance rating of the layoff event to real estate market trends.

Available options:

Completely Irrelevant,

Irrelevant,

Very Poor,

Poor,

Fair,

Good,

Very Good,

Excellent

additional_filters.layoff.is_relevant_for_real_estate

enum<string>

True if the layoff impacts real estate market; false otherwise.

Available options:

true,

false

additional_filters.layoff.layoff_reason

string

The stated reason provided for the layoff.

additional_filters.layoff.location

object

Filter criteria for the location of the layoff. All fields support both exact and partial matching.

additional_filters.layoff.max_number_of_people_laid_off

object

The maximum number of employees affected when a range is specified.

additional_filters.layoff.min_number_of_people_laid_off

object

The minimum number of employees affected when a range is specified.

additional_filters.layoff.number_of_people_laid_off

object

The exact number of employees affected by the layoff.

additional_filters.layoff.percentage_of_people_laid_off

object

The percentage of total workforce affected by the layoff.

additional_filters.layoff.summary

string

The detailed description of the layoff event.

additional_article_fields

enum<string>[]

Additional article fields to include in the response. Only applicable when attach_articles_data is true.

Available options:

description,

content,

published_date,

published_date_precision,

author,

authors,

journalists,

domain_url,

full_domain_url,

name_source,

extraction_data.parent_url,

is_headline,

paid_content,

rights,

rank,

is_opinion,

language,

word_count,

twitter_account,

all_links,

all_domain_links,

nlp.theme,

nlp.summary,

nlp.sentiment,

nlp.ner_PER,

nlp.ner_ORG,

nlp.ner_MISC,

nlp.ner_LOC

Response

200

application/json

Search results containing matched events.

message

string

required

The status message of the search operation.

count

integer

required

The total number of events returned.

events

object[]

required

The list of matched events.

events.id

string

required

The unique identifier of the event.

events.event_type

enum<string>

required

The specific type of the event.

Available options:

layoff,

data_breach,

fundraising

events.global_event_type

enum<string>

required

The high-level category of the event.

Available options:

Layoff,

DataMonitoring,

Finance

events.associated_article_ids

string[]

required

The identifiers of news articles associated with this event.

events.extraction_date

string

required

The timestamp when the event was extracted from news sources.

events.event_date

string

required

The timestamp when the event occurred.

events.company_name

string

required

Name of the company that conducted the layoff.

events.articles

object[]

Array of source articles. Only present when attach_articles_data is true in the request. Access individual articles using array index, e.g.:

First article: events.articles[0]
Second article: events.articles[1]

By default, only returns id, title, link, and media fields. To request more fields, add them to the additional_article_fields array in the search request.

events.layoff

object

Was this page helpful?

Suggest edits Raise issue

Get event fields Check API health status

curl --request POST \
  --url https://events.newscatcherapi.xyz/api/events_search \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: <api-key>' \
  --data '{
  "event_type": "layoff",
  "attach_articles_data": false,
  "additional_filters": {
    "company_name": "<string>",
    "event_date": {
      "gte": "<string>",
      "lte": "<string>"
    },
    "extraction_date": {
      "gte": "<string>",
      "lte": "<string>"
    },
    "layoff.how_much_related": "Completely Irrelevant",
    "layoff.is_relevant_for_real_estate": "true",
    "layoff.layoff_reason": "<string>",
    "layoff.location": {
      "country": "<string>",
      "city": "<string>",
      "raw_location": "<string>",
      "county": "<string>",
      "state": "<string>"
    },
    "layoff.max_number_of_people_laid_off": {
      "gte": 123,
      "lte": 123
    },
    "layoff.min_number_of_people_laid_off": {
      "gte": 123,
      "lte": 123
    },
    "layoff.number_of_people_laid_off": {
      "gte": 123,
      "lte": 123
    },
    "layoff.percentage_of_people_laid_off": {
      "gte": 123,
      "lte": 123
    },
    "layoff.summary": "<string>"
  },
  "additional_article_fields": [
    "description",
    "published_date",
    "nlp.summary"
  ]
}'

{
  "message": "Success",
  "count": 25,
  "events": [
    {
      "id": "n1jk-pQBvyT_ytpRpzBn",
      "event_type": "layoff",
      "global_event_type": "Layoff",
      "associated_article_ids": [
        "<string>"
      ],
      "extraction_date": "2023-11-07T05:31:56Z",
      "event_date": "2023-11-07T05:31:56Z",
      "articles": [
        {
          "id": "<string>",
          "title": "<string>",
          "link": "<string>",
          "media": "<string>"
        }
      ],
      "company_name": "<string>",
      "layoff": {
        "summary": "<string>",
        "layoff_reason": "<string>",
        "max_number_of_people_laid_off": 123,
        "min_number_of_people_laid_off": 123,
        "number_of_people_laid_off": 123,
        "percentage_of_people_laid_off": 123,
        "how_much_related": "Completely Irrelevant",
        "is_relevant_for_real_estate": true,
        "location": [
          {
            "country": "<string>",
            "city": "<string>",
            "raw_location": "<string>",
            "county": "<string>",
            "state": "<string>"
          }
        ]
      }
    }
  ]
}

Overview

How to

Event types

Endpoints

Authorizations

Body

Response