Getting Started
The Spider News API presents news data in the form of entities and connections. Combined, these data types create a massive web of interactions.
There are 3 primary data routes:
- Connections — a route for finding connections from a specific entity, or bulk connections in general
- Pathfinding — a route for finding complex multi-connection paths between entities
- Entities — a route for searching through nodes to find their entity type or UUID
Each route is billed using "rows". One row corresponds to one unique entity or unique connection returned. Consult the API Keys & Usage page for more information.
What is an Entity?
A news entity is a particular named object, such as a person, organization, or product. Each entity is represented as a node:
{
"rows_returned": 1,
"entities": [
{
"ent_uuid": "2dae89f6-6804-47d6-969e-810eb6620c66",
"ent_name": "Raul Castro",
"ent_type": "PERSON",
"ent_aliases": [],
"occurrence_count": "2",
"sml": 1
}
]
}Spider News classifies all news entities into 12 types:
| Entity Type | Description |
|---|---|
| ORG | Organization, Company |
| PRODUCT | Product, Invention, Idea |
| GPE | Geopolitical Entity, Country, State |
| PERSON | Person (real or fictional) |
| TITLE | Title, Position, Rank |
| FAC | Facility, Airport, Factory |
| TECHNOLOGY | Technology |
| LAW | Law, Ruling, Regulation |
| LOC | Location, Landmark, Direction |
| NORP | Nationalities, Religious or Political Groups |
| THREAT | Cybersecurity Vulnerability, or Threat Actor |
| EVENT | Event, Period of Time |
Note that one string name may relate to multiple news entities. Usually, this represents something that is multi-faceted. For example:
{
"rows_returned": 2,
"entities": [
{
"ent_uuid": "ab33916f-395d-4e36-b7d6-3a773f39bfc5",
"ent_name": "Facebook",
"ent_type": "PRODUCT",
"ent_aliases": [],
"occurrence_count": "151",
"sml": 1
},
{
"ent_uuid": "314e3b58-0283-483b-b996-1441aa63bfca",
"ent_name": "Facebook",
"ent_type": "ORG",
"ent_aliases": [],
"occurrence_count": "82",
"sml": 1
}
]
}What is a Connection?
A news connection is some semantic relationship between two entities. Each connection is represented with an edge. Note that these edges do not have directionality.
{
"rows_returned": 3,
"connections": [
{
"source_entity": {
"ent_name": "Raul Castro",
"ent_type": "PERSON",
"ent_uuid": "f4149762-a2b9-4264-b0a6-fc61cb343a96",
"ent_aliases": []
},
"connection_data": {
"type": "HasTitle",
"article_title": "A Tale of Two Summits",
"article_url": "https://justworldeducational.org/?p=7222",
"article_site": "https://justworldeducational.org/",
"article_date": "2022-06-21",
"context": "shook hands with Cuban President Raul Castro"
},
"target_entity": {
"ent_name": "Cuban President",
"ent_type": "TITLE",
"ent_uuid": "2e6f8707-6a58-4232-9225-428a9668c6ff",
"ent_aliases": []
}
}
]
}Spider News classifies all news connections into 25 types:
| Connection Type | Description |
|---|---|
| Coop | Cooperation |
| Oppo | Opposition |
| Legal | Legal Interaction, Lawsuit, Agreement |
| Deal | Financial Interaction, Agreement |
| GoodsTran | Goods Transfer |
| Sanction | Sanctions |
| Merger | Mergers |
| Acquisition | Aquisiton |
| IsPartOf | X is part of Y |
| IsA | X belongs to a NORP group ("Google is an American company") |
| HasTitle | PERSON has TITLE |
| Competitors | ORG and ORG are competitors with each other in the same space |
| EquivalentTo | X does the same thing as Y |
| BetterThan | X supersedes Y |
| IsSubclassOf | X is a specific instance of a broader Y |
| WorksFor | X works for Y |
| Owns | X is the owner of Y |
| OperatesIn | X is based in or operates in or is located in Y |
| IsFrom | X originates from Y ("John is from England") |
| Uses | X uses Y |
| Produces | X produces Y |
| Affects | THREAT affects Y |
| Prevents | X prevents THREAT |
| ParticipatesIn | X participates/participated in EVENT |
| KnownAssociates | PERSON is associated/worked with PERSON |