# Signal AI Affinity API **Canonical:** https://apis.io/apis/signal-ai/signal-ai-affinity-api/ **Provider:** Signal AI — https://apis.io/providers/signal-ai/ **Base URL:** https://api.signal-ai.com **Documentation:** https://signal-ai.com/solutions/api Signal AI Affinity API is one of 11 APIs that [Signal AI](https://apis.io/providers/signal-ai/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Affinity. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and an API reference. The Affinity API endpoints allow API users to leverage the power of the Signal AI Knowledge Graph, derived from billions of documents and updated regularly. The Signal AI Knowledge Graph consists of: * **nodes** which represent concepts such as entities and topics * **edges** represent connections describing relationships between these concepts Using the Affinity API, users can retrieve data for hundreds of thousands of entities and topics. The sole relationship type currently accessible via the Affinity API is proximity. ## Proximity Proximity represents how closely entities and topics are associated in the news and other types of content processed by Signal AI. ### What is proximity? The proximity between an entity (e.g. Tesla) and a topic (e.g. Product recall) is a measure of how they are related over a period of time (e.g. a certain month) as perceived in the news (almost all sources we ingest into the Signal platform). It reflects the likelihood of the entity and topic in question being mentioned together, with 0 meaning the two are very unlikely to appear together, and 1 meaning they are most likely to appear together (NB: the scale is not linear.) We measure this by observing the mentions of the topic, the (salient) mentions of the entity and their (salient) co-mentions. As opposed to relying only on the volume of co-mentions, the proximity score captures how significant these co-mentions are based on the overall volume of coverage for both the entity and the topic. **For example, if the entity has a high number of co-mentions with a topic, but the topic is very common (e.g Social Media), we may assign a low proximity score. On the other hand if there are only a few co-mentions with a very niche topic, we may assign a high proximity score.** The proximity score is based on the normalized Google Distance (from Information distance theory) and it has a value between 0 and 1: - A score of 0 means the two concepts are not related and never or rarely co-mentioned together; - The higher the score is, the more related the concepts are and the higher the chance is of observing significant co-mentions. - A proximity close to 1 means that if one of the concepts is mentioned in an article, it is most likely that the other concept will also be mentioned in the article. To illustrate how proximity is implemented, consider this conceptual representation of the Signal AI Knowledge Graph below: ![](/assets/img/affinity_example.svg) In this graph, we see four nodes: two organizations (PepsiCo and American Chemical Society) and two topics (Food and Beverage and Chemicals). We also see three edges each representing a proximity relationship: (PepsiCo and Food and Beverage), (PepsiCo and Chemicals) and (American Chemical Society and Chemicals). We can infer from these edges that PepsiCo has a closer association to Food and Beverage than Chemicals. Also we can infer that American Chemical Society has a stronger connection to Chemicals than PepsiCo. ### Using the proximity score The proximity score can be used in different ways: #### 1. Discovery We can identify the closest topics to an entity by ranking them according to their proximity score. Note that if we simply use the volume of co-mentions to rank topics, we will end up with the common topics (which might be considered noise). Likewise, we can do the opposite and identify the organizations (or any other type of entities) that are closest to a certain topic. Note, if we simply use the volume of co-mentions to rank organizations, we will end up with the common ones which are often mentioned in news articles, e.g. BBC, NASDAQ, UK, US #### 2. Comparison - **Comparing Entities**: We can compare two entities on how they are related to certain topics, ie. which one is more related. A higher proximity score means more relatedness to a topic. Note that this is different from comparing them based on the volume (number of articles on topic). For example one big company may have way more articles on a topic than a smaller company, but the smaller company may have a higher proximity. This is because it has way fewer mentions than the big company overall and a few articles on the topic contribute to a higher proximity score. - **Comparing Topics**: Likewise, we can compare two topics on how they are related to certain entities. A higher proximity score means more relatedness to an entity. - **Comparison over time**: We can say if the proximity between an entity and topic has increased or decreased from one month to another by comparing their proximity score in those months. NB: While the proximity scores are ordered, they are not linear. *This means you can't easily interpret the difference between proximity scores i.e. the difference between 0 and 0.1 proximity is not the same as the difference between 0.4 and 0.5 proximity.* ### Proximity metadata Each proximity relationship returned contains the following metadata: - `proximity-score`: the proximity score in the range `[0..1]` as described above - `sentiment-score`: for a proximity relationship between an entity and a topic, this score represents the sentiment towards the entity with regards to its relationship to the topic. The sentiment score ranges between `[-1..1]` and is computed as follows (taking into account salient entity mentions only: ``` #(positive entity/topic co-mentions) - #(negative entity/topic co-mentions) / #(entity/topic co-mentions) ``` ### Using proximity Using proximity relationships, one can uncover unknowns and insights on a large scale. The API offers one endpoint to allow the users to query and explore proximity relationships. Please note that only the last 15 months of data can be queried. ## Operations (1) | Method | Path | Summary | |---|---|---| | POST | `/affinity` | Explore concept connections (powered by the Signal AI Knowledge Graph) | ## Machine-readable artifacts (4) - **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/signal-ai/refs/heads/main/openapi/signal-ai-affinity-api-openapi.yml - **Documentation** — https://api.signal-ai.com/docs - **APIReference** — https://api.signal-ai.com/docs - **APIsJSON** — https://raw.githubusercontent.com/api-evangelist/signal-ai/refs/heads/main/apis.yml ## Other Signal AI APIs (10) - [Signal AI Categories API](https://apis.io/apis/signal-ai/signal-ai-categories-api/) - [Signal AI Content Metrics API](https://apis.io/apis/signal-ai/signal-ai-content-metrics-api/) - [Signal AI Content Search API](https://apis.io/apis/signal-ai/signal-ai-content-search-api/) - [Signal AI Entities API](https://apis.io/apis/signal-ai/signal-ai-entities-api/) - [Signal AI Events API](https://apis.io/apis/signal-ai/signal-ai-events-api/) - [Signal AI Openapi.json API](https://apis.io/apis/signal-ai/signal-ai-openapi-json-api/) - [Signal AI Publication sources API](https://apis.io/apis/signal-ai/signal-ai-publication-sources-api/) - [Signal AI Risk Events API](https://apis.io/apis/signal-ai/signal-ai-risk-events-api/) - [Signal AI Topics API](https://apis.io/apis/signal-ai/signal-ai-topics-api/) - [Signal AI Organisation API](https://apis.io/apis/signal-ai/signal-ai-organisation-api/) ## Tags Affinity --- Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/signal-ai/signal-ai-affinity-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/signal-ai/.