Subscribe to the stream

Choose what the Firehose sends you: the filters to apply, the fields to include, and where in the stream to start.

Explanation

Tells the Firehose what you want: which filters to apply, which parts of each document to send, and where in the stream to start. Use it to receive only the documents you need, and to save bandwidth by never being sent the rest, however fast the web moves.

SEND{"type": "subscribe"}Get access

Request

Frame fields

JSON text frame

typestringrequiredbody

Always subscribe.

Example: subscribe

subscriptionstringbody

A name for this subscription, 1 to 64 letters, digits, hyphens or underscores. Reusing an active name with the same key replaces the previous connection. Default: default.

Example: energy-desk

resumestring | objectbody

Where to start: "latest" (default), {"cursor": "..."} or {"from_time_ms": 1793880000000}.

Example: "latest"

filtersobjectbody

Server-side filters. Omit to receive everything. See Filter syntax.

Example: {"ontologies": [{"ontology": "gics", "match": {"sector": "Energy"}}]}

fieldsstring[]body

Return only these parts of each document, such as page.title or ontologies. Omit for the whole document, untouched.

Example: ["page.title", "ontologies", "tickers"]

Filter syntax

filters

Filters run on NOSIBLE's side, so unmatched documents never use your bandwidth. Different kinds combine with AND, clauses within a kind with OR, and an omitted kind or empty list matches everything. Text matching is case-insensitive, but entity names and ticker symbols must match in full. The properties inside one clause must match the same row.

Each kind takes up to 100 entries. Setting has_tickers to false together with a non-empty tickers filter cannot match any document. The hash, published_timestamp and visited_timestamp fields are metadata and cannot be filtered.

filters.ontologies[]: classification

ontologystring

Required. One of: asset_class, ekman7_emotion, emdat, gics, iab, icd11, iptc_genre, iptc_media_topics, media_frame, mitre_attack, nosible, plover, schema_org_event, sdgs, sportsml.

Example: gics

matchobject

Hierarchy fields that must equal the classification row. Omit to match the whole family.

Example: {"sector": "Energy"}

min_probabilitynumber

Minimum probability from 0 to 1.

Example: 0.7

Path fields to match, by family

asset_classpath

match keys: main_class, sub_class.

ekman7_emotionpath

match keys: label.

emdatpath

match keys: disaster_group, disaster_subgroup, disaster_type.

gicspath

match keys: sector, industry_group, industry, sub_industry.

iabpath

match keys: tier_1, tier_2, tier_3, tier_4.

icd11path

match keys: chapter, block.

iptc_genrepath

match keys: label.

iptc_media_topicspath

match keys: level_1, level_2, level_3.

media_framepath

match keys: label.

mitre_attackpath

match keys: tactic, technique, subtechnique.

nosiblepath

match keys: category, subcategory, event.

ploverpath

match keys: event, mode, context.

schema_org_eventpath

match keys: label.

sdgspath

match keys: goal, target.

sportsmlpath

match keys: sport, event_type.

filters.locations[]: geography

continentstring

Continent of a resolved location. A clause needs at least one of continent, region or country.

Example: Europe

regionstring

Region or state.

Example: Western Europe

countrystring

Country name.

Example: France

filters.entities[]: named entities

labelstring

NER label: PERSON, ORG, GPE, LOC or PRODUCT.

Example: ORG

namestring

Complete entity name. A clause needs a label, a name or both.

Example: Shell

filters.tickers and filters.has_tickers

tickers[]string[]

Match a document that has any of these ticker symbols, in full.

Example: ["AAPL", "SHEL.L"]

has_tickersboolean

True requires at least one ticker match. False requires none. Omit it to accept both.

Example: true

filters.languages and filters.netloc

languages[]string[]

Match the document's highest-scoring language code.

Example: ["en", "fr"]

netloc[]string[]

Match request.netloc. A host also matches its subdomains.

Example: ["reuters.com"]

Response

Frame you receive

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

typestring

Always subscribed.

Example: subscribed

subscriptionstring

Your subscription name.

Example: energy-desk

sourcestring

Where delivery starts: latest, cursor or time.

Example: latest

cursorstring

Opaque starting position.

Example: eyJ2IjoxLC4uLn0

time_msinteger

When the server prepared this message, UTC Unix milliseconds.

Example: 1793880000100

Errors and close codes

WebSocket

TEXTA JSON text frame, shown in the response example.

1008bad_request — A frame, filter, fields entry or resume value was invalid. The message says which.

1000forbidden — This key cannot resume from a cursor or time, or its access changed. Use latest.

1000cursor_expired — The cursor or time is older than the 24-hour replay window. Resume with latest.

1000timeout — You did not authenticate or subscribe in time.

Subscribe to the stream

Explanation

Request

Frame fields

Filter syntax

Response

Frame you receive

Errors and close codes

Related in NOSIBLE