Machine-readable docs: llms.txt (index), llms-full.txt (complete reference), OpenAPI specification.

NewsAPI.ai API Documentation | Endpoints, SDKs, and Key Access Explained: Access the complete API documentation for NewsAPI.ai. Learn about endpoints, parameters, Python and Node.js SDKs, rate limits, and response codes. Get started quickly with free registration and your API key.
Semantic Annotation API | Identify Entities in Text with NewsAPI.ai: Use NewsAPI.ai's annotation tool to uniquely identify people, locations, organizations, and concepts within documents. Supports over 100 languages with semantic annotations linked to Wikipedia pages.
Semantic Similarity API | Compare Cross-Language Document Similarity with NewsAPI.ai: Compare the semantic similarity between two documents in different languages with NewsAPI.ai's Semantic Similarity API. Identify shared entities and gain deep contextual insights.
Get Articles API | Search News and PR Content with Advanced Filters from NewsAPI.ai: Find news articles matching one or more search conditions with NewsAPI.ai's Get Articles API. Use advanced search parameters to retrieve the most relevant content, from keywords to locations.
Get Articles for Topic Page API | Topic-Based News Search with NewsAPI.ai: Retrieve news articles that match a user-generated topic page with NewsAPI.ai's Get Articles for Topic Page API. Use unique URIs to easily filter by concepts, keywords, news sources, and more.
Stream New News Articles in Real-Time with NewsAPI.ai: Access new articles added to Event Registry with NewsAPI.ai's 'Stream of New Articles' endpoint. Set up filters to get the latest news content directly to your application.
Search and Retrieve Events by Keyword or Concept with NewsAPI.ai: Discover events related to your interests with NewsAPI.ai. Use the Get Events endpoint to find events that match specific keywords, concepts, categories, and more.
Retrieve Events for User-Generated Topic Pages with NewsAPI.ai: Use NewsAPI.ai's Get Events for a Topic Page to retrieve events that match your user-generated topics. Customize searches with topic-specific URIs.
Retrieve Comprehensive Event Details with NewsAPI.ai: Obtain comprehensive details about specific events using NewsAPI.ai's Get Event Details endpoint. Retrieve articles, summaries, and other event metadata.
Access Real-Time Stream of Events with NewsAPI.ai: Access real-time streams of events added or updated in the last few minutes with NewsAPI.ai's Stream of Events endpoint. Filter by language, keywords, or locations.
Retrieve the Latest Breaking Events with NewsAPI.ai: Get a list of the most recent breaking events with NewsAPI.ai's Breaking Events endpoint. Retrieve events based on their breaking score and reporting intensity.
Suggest Concepts for API Queries with NewsAPI.ai: Find concept URIs with NewsAPI.ai's Suggest Concepts API. Retrieve concept details for various API queries by searching partial or full concept labels.
Suggest Categories for API Queries with NewsAPI.ai: Retrieve category URIs with NewsAPI.ai's Suggest Categories API. Search for categories by partial or full label to assist in filtering various API calls.
Suggest News Sources for API Queries with NewsAPI.ai: Use NewsAPI.ai's Suggest Sources API to retrieve news source URIs. Search by source name or domain name to assist in filtering API requests.
Suggest Authors for API Queries with NewsAPI.ai: Find author URIs with NewsAPI.ai's Suggest Authors API. Retrieve authors by name, including partial matches, to assist in API queries.
Suggest Locations for API Queries with NewsAPI.ai: Retrieve location URIs using NewsAPI.ai's Suggest Locations API. Search by city or country name to get relevant URIs for API filtering.
Suggest Event Types for API Queries with NewsAPI.ai: Find event type URIs with NewsAPI.ai's Suggest Event Types API. Retrieve event types for API calls by providing a label or prefix.
Terminology and Definitions for NewsAPI.ai & Event Registry: Explore terminology used in Event Registry and NewsAPI.ai. Learn about articles, events, concepts, categories, sources, and locations for API queries.
Supported Languages and Language Codes | NewsAPI.ai: See the full list of languages supported by NewsAPI.ai and Event Registry, with the language codes to use in the lang parameter of your API calls.
Advanced Search Query Language | NewsAPI.ai Documentation: Build advanced NewsAPI.ai queries with AND, OR and NOT logic. Learn the JSON query language to combine keywords, concepts, categories, sources and filters.
Keyword Search Modes — Phrase, Boolean & Simple | NewsAPI.ai: Learn NewsAPI.ai's keyword search modes: exact phrase matching, full Boolean logic (AND/OR/NOT, NEAR, NEXT), and relevance-based simple search, with examples.
Response Format and Data Models | NewsAPI.ai Documentation: Understand the response format of NewsAPI.ai. Explore the data models for articles, events, concepts, categories, sources and other returned JSON objects.
MCP Integration Guide | NewsAPI.ai for AI Assistants: Connect NewsAPI.ai to Claude, Codex, Cursor and other AI assistants with the hosted Model Context Protocol (MCP) server. Search news, track events, find mentions and use topic pages.
n8n Integration Overview | NewsAPI.ai Automation: Automate news workflows with NewsAPI.ai and n8n. Learn how to set up API credentials and connect Event Registry endpoints to no-code n8n automations.
n8n Example: Content Research Workflow | NewsAPI.ai: Build a content research assistant with NewsAPI.ai and n8n. Step-by-step workflow to fetch, split and email relevant news articles automatically.
n8n Example: News Alert System | NewsAPI.ai: Create a news alert system with NewsAPI.ai and n8n. Schedule searches, filter results with conditions, and send email alerts for breaking news automatically.
n8n Example: Sentiment Analysis Workflow | NewsAPI.ai: Track news sentiment with NewsAPI.ai and n8n. Build a workflow that collects articles, extracts sentiment, and logs results to Google Sheets for analysis.
Named entity recognition | Event Registry API documentation: Reference for the Named entity recognition endpoint of the Event Registry API: parameters, request examples and the response format.
Categorize | Event Registry API documentation: Reference for the Categorize endpoint of the Event Registry API: parameters, request examples and the response format.
Sentiment | Event Registry API documentation: Reference for the Sentiment endpoint of the Event Registry API: parameters, request examples and the response format.
Extract article information | Event Registry API documentation: Reference for the Extract article information endpoint of the Event Registry API: parameters, request examples and the response format.
Detect language | Event Registry API documentation: Reference for the Detect language endpoint of the Event Registry API: parameters, request examples and the response format.
Get article details | Event Registry API documentation: Reference for the Get article details endpoint of the Event Registry API: parameters, request examples and the response format.
Get mentions | Event Registry API documentation: Reference for the Get mentions endpoint of the Event Registry API: parameters, request examples and the response format.
API Usage | Event Registry API documentation: Reference for the API Usage endpoint of the Event Registry API: parameters, request examples and the response format.

Annotate

Uniquely identify people, locations, organizations and things mentioned in the user-provided document.

The API call can be used to semantically annotate the provided document. The semantic annotation includes identification of people, locations, organizations and things mentioned in the document. All annotations will have a unique URI that will correspond to the URL of the Wikipedia page that will match the concept.

The annotations can be generated for over 100 different languages. Each returned annotation will contain a property url that will point to the concept in the Wikipedia for that language. The secUrl parameter will point to the concept in the English Wikipedia, if the page for it exists.

EndpointGET | POSThttp://analytics.eventregistry.org/api/v1/annotate

HeadersContent-Type: application/json

Request body

            
            {
  "text": "Microsoft released a new version of Windows OS.",
  "apiKey": "YOUR_API_KEY"
}

            
            {
  "annotations": [
    {
      "title": "Singapore",
      "url": "http://en.wikipedia.org/wiki/Singapore",
      "lang": "en",
      "pageRank": 0.02274951488845428,
      "secLang": "en",
      "secTitle": "Singapore",
      "secUrl": "http://en.wikipedia.org/wiki/Singapore",
      "wikiDataItemId": "Q334",
      "dbPediaTypes": [
        "PopulatedPlace",
        "Place",
        "Country"
      ],
      "dbPediaIri": "http://dbpedia.org/resource/Singapore",
      "support": [
        {
          "wFrom": 0,
          "wTo": 0,
          "chFrom": 0,
          "chTo": 8,
          "pMentionGivenSurface": 0.3624772063561704,
          "pageRank": 0.00733049123934485,
          "prbConfidence": 0.5945097191539227,
          "entropy": 0.3062825090018834,
          "text": "Singapore",
          "wikiLang": "en"
        }
      ],
      "type": "loc",
      "wgt": 0.6666666666666666
    },
    {
      "title": "Lee Hsien Loong",
      "url": "http://en.wikipedia.org/wiki/Lee_Hsien_Loong",
      "lang": "en",
      "pageRank": 0.03712173018650666,
      "secLang": "en",
      "secTitle": "Lee Hsien Loong",
      "secUrl": "http://en.wikipedia.org/wiki/Lee_Hsien_Loong",
      "wikiDataItemId": "Q57643",
      "dbPediaTypes": [
        "Person",
        "Agent",
        "President",
        "Politician",
        "OfficeHolder"
      ],
      "dbPediaIri": "http://dbpedia.org/resource/Lee_Hsien_Loong",
      "support": [
        {
          "wFrom": 4,
          "wTo": 6,
          "chFrom": 27,
          "chTo": 41,
          "pMentionGivenSurface": 0.8918918918918919,
          "pageRank": 0.01803701194257155,
          "prbConfidence": 1,
          "entropy": 0,
          "text": "Lee Hsien Loong",
          "wikiLang": "en"
        },
        {
          "chFrom": 563,
          "chTo": 565,
          "wFrom": 105,
          "wTo": 105,
          "pageRank": null,
          "pMentionGivenSurface": null,
          "text": "Lee",
          "wikiLang": "en"
        },
        {
          "chFrom": 1118,
          "chTo": 1120,
          "wFrom": 219,
          "wTo": 219,
          "pageRank": null,
          "pMentionGivenSurface": null,
          "text": "Lee",
          "wikiLang": "en"
        }
      ],
      "type": "person",
      "wgt": 0.6984843176884913
    },
    {
      "title": "Mediacorp",
      "url": "http://en.wikipedia.org/wiki/Mediacorp",
      "lang": "en",
      "pageRank": 0.020642583639049,
      "secLang": "en",
      "secTitle": "Mediacorp",
      "secUrl": "http://en.wikipedia.org/wiki/Mediacorp",
      "wikiDataItemId": "Q1368796",
      "dbPediaTypes": [],
      "dbPediaIri": "",
      "support": [
        {
          "wFrom": 110,
          "wTo": 110,
          "chFrom": 588,
          "chTo": 596,
          "pMentionGivenSurface": 0.4163602941176471,
          "pageRank": 0.008420185972856556,
          "prbConfidence": 1,
          "entropy": 0,
          "text": "Mediacorp",
          "wikiLang": "en"
        }
      ],
      "type": "wiki",
      "wgt": 0.3333333333333333
    },
    {
      "#META ITEM": "other concepts..."
    }
  ],
  "minPageRank": 0.01728619391379328,
  "maxDfThreshold": 834348,
  "altLabelSetsUsed": [
    "en"
  ],
  "linkSourcesAvailable": true,
  "timeTotalMs": 58.456,
  "timeAnnotationMs": 58.456,
  "timeBuildJsonMs": 0,
  "incIdxTimestampUtc": "",
  "fnRegIdx": "enwiki-20220120-pages-articles-index3.bin",
  "fnWikiData": "wikidata-20200803-all.bin",
  "settings": {
    "pageRankSqThreshold": 0.95,
    "applyPageRankSqThreshold": true,
    "minPMentionGivenPhrase": 0.03,
    "maxMentionEntropy": -1,
    "maxTargetsPerMention": 20,
    "useLogLinkCounts": false,
    "candSelectionUseLinearizedPageRank": false,
    "candSelectionPageRankThreshold": 0,
    "candSelectionCosineWeight": 0,
    "candSelectionLinkCtxCosineWeight": 0,
    "candSelectionUseLinkProb": "log",
    "semanticSimilarity": "in",
    "secondaryAnnotLanguage": "en",
    "minLinkFrequency": 3,
    "minLinkRelFrequency": 0.01,
    "nTopDfWordsToIgnore": 200,
    "nWordsToIgnoreFromList": 200,
    "extraVocabsToInclude": [],
    "altLabelSetsToUse": [
      "*"
    ]
  },
  "language": "en",
  "languageAutodetectInfo": "Language autodetected as \"en\" (0).",
  "languageAutodetectDetails": {
    "topLangNo": 0,
    "topLangCode": "en",
    "candidates": [
      {
        "langNo": 0,
        "langCode": "en",
        "percent": 99,
        "normScore": 1190
      },
      {
        "langNo": 26,
        "langCode": "unknown_26",
        "percent": 0,
        "normScore": 0
      },
      {
        "langNo": 26,
        "langCode": "unknown_26",
        "percent": 0,
        "normScore": 0
      }
    ],
    "textBytes": 1134,
    "validPrefBytes": 1176,
    "isReliable": true,
    "chunks": []
  }
}

            
            {
  "type": "object",
  "properties": {
    "annotations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "example": "http://en.wikipedia.org/wiki/Microsoft"
          },
          "title": {
            "type": "string",
            "example": "Microsoft"
          },
          "lang": {
            "type": "string",
            "example": "eng"
          },
          "secUrl": {
            "type": "string",
            "example": "http://en.wikipedia.org/wiki/Microsoft"
          },
          "secTitle": {
            "type": "string",
            "example": "Microsoft"
          },
          "secLang": {
            "type": "string",
            "example": "eng"
          },
          "dbPediaIri": {
            "type": "string",
            "example": "http://dbpedia.org/resource/Microsoft"
          },
          "dbPediaTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Agent",
              "Organisation",
              "Company"
            ]
          },
          "type": {
            "type": "string",
            "example": "org"
          },
          "wgt": {
            "type": "double",
            "example": 0.9
          },
          "pageRank": {
            "type": "double",
            "example": 0.254
          },
          "wikiDataItemId": {
            "type": "string",
            "example": "Q2283"
          },
          "wikiDataClassIds": {
            "type": "array",
            "example": "Q2283",
            "items": {
              "type": "string"
            }
          },
          "support": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "chFrom": {
                  "type": "integer",
                  "example": 0
                },
                "chTo": {
                  "type": "integer",
                  "example": 8
                },
                "pMentionGivenSurface": {
                  "type": "double",
                  "example": 0.255
                },
                "text": {
                  "type": "string",
                  "example": "Microsoft"
                },
                "wFrom": {
                  "type": "integer",
                  "example": 0
                },
                "wTo": {
                  "type": "integer",
                  "example": 0
                },
                "wikiLang": {
                  "type": "string",
                  "example": "en"
                }
              }
            }
          }
        }
      }
    },
    "spaces": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "words": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "normWords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "ranges": {
      "type": "array",
      "items": {
        "type": "integer"
      }
    },
    "minPageRank": {
      "type": "integer"
    },
    "maxDfThreshold": {
      "type": "integer"
    },
    "altLabelSetsUsed": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "linkSourcesAvailable": {
      "type": "boolean"
    },
    "verbs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iFrom": {
            "type": "integer"
          },
          "iTo": {
            "type": "integer"
          },
          "normForm": {
            "type": "string"
          },
          "synsetIds": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      }
    },
    "nouns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iFrom": {
            "type": "integer"
          },
          "iTo": {
            "type": "integer"
          },
          "normForm": {
            "type": "string"
          },
          "synsetIds": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      }
    },
    "adjectives": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iFrom": {
            "type": "integer"
          },
          "iTo": {
            "type": "integer"
          },
          "normForm": {
            "type": "string"
          },
          "synsetIds": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      }
    },
    "adverbs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "iFrom": {
            "type": "integer"
          },
          "iTo": {
            "type": "integer"
          },
          "normForm": {
            "type": "string"
          },
          "synsetIds": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      }
    },
    "timeTotalMs": {
      "type": "integer"
    },
    "timeAnnotationMs": {
      "type": "integer"
    },
    "timeBuildJsonMs": {
      "type": "integer"
    },
    "incIdxTimestampUtc": {
      "type": "string"
    },
    "fnRegIdx": {
      "type": "string"
    },
    "fnWikiData": {
      "type": "string"
    },
    "settings": {
      "type": "object",
      "properties": {
        "pageRankSqThreshold": {
          "type": "integer"
        },
        "applyPageRankSqThreshold": {
          "type": "boolean"
        },
        "minPMentionGivenPhrase": {
          "type": "integer"
        },
        "maxMentionEntropy": {
          "type": "integer"
        },
        "maxTargetsPerMention": {
          "type": "integer"
        },
        "useLogLinkCounts": {
          "type": "boolean"
        },
        "candSelectionUseLinearizedPageRank": {
          "type": "boolean"
        },
        "candSelectionPageRankThreshold": {
          "type": "integer"
        },
        "candSelectionCosineWeight": {
          "type": "integer"
        },
        "candSelectionLinkCtxCosineWeight": {
          "type": "integer"
        },
        "candSelectionUseLinkProb": {
          "type": "string"
        },
        "semanticSimilarity": {
          "type": "string"
        },
        "secondaryAnnotLanguage": {
          "type": "string"
        },
        "minLinkFrequency": {
          "type": "integer"
        },
        "minLinkRelFrequency": {
          "type": "integer"
        },
        "nWordsToIgnoreFromList": {
          "type": "integer"
        },
        "extraVocabsToInclude": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {}
          }
        },
        "altLabelSetsToUse": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "language": {
      "type": "string"
    },
    "languageAutodetectInfo": {
      "type": "string"
    },
    "languageAutodetectDetails": {
      "type": "object",
      "properties": {
        "topLangNo": {
          "type": "integer"
        },
        "topLangCode": {
          "type": "string"
        },
        "candidates": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "langNo": {
                "type": "integer"
              },
              "langCode": {
                "type": "string"
              },
              "percent": {
                "type": "integer"
              },
              "normScore": {
                "type": "integer"
              }
            }
          }
        },
        "textBytes": {
          "type": "integer"
        },
        "validPrefBytes": {
          "type": "integer"
        },
        "isReliable": {
          "type": "boolean"
        },
        "chunks": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}

Parameters

apiKey string (required)

Your API key

text string (required)

Define a text that you'll like to see annotated.

Additional parameters

Click to see additional parameters

minLinkFrequency integer

The minimum number of times the phrase should appear in the link in order for use to use it as a candidate for the annotation.

Default value: 3

minLinkRelFrequency double

Consider the candidate only if the given text points to the candidate with probability above this value. Value between 0 and 1.

Default value: 0.01

nWordsToIgnoreFromList integer

Use this setting to ignore common phrases. If a phrase consists entirely of very frequent words, it will be ignore. A word is considered frequent if it is one of the most frequent words (in terms of document frequency) in the Wikipedia of the corresponding language. If 0 it will disable this heuristic.

Default value: 200

minPMentionGivenPhrase double

Probability that the given phrase, if found on Wikipedia, is annotated with the concept. If non-zero, it can help to remove the common words.

Default value: 0.03

pageRankSqThreshold double

Probability that the given phrase, if found on Wikipedia, is annotated with the concept. If non-zero, it can help to remove the common words.

Default value: 0.95

applyPageRankSqThreshold boolean

Apply pageRankSqThreshold to the requested response.

Annotate

Request body

Example output

Output schema