Search API quickstart

One request that returns the latest articles matching your search, with their text, duplicates grouped, and topics, entities and readership data. Copy it, add your token, and run it.

Searches are sent as POST requests to https://api.opoint.com/search/, with a JSON body. The body has two parts: searchterm, what to search for, and params, what to return.

You need an API token. Send it in the Authorization header as Token yourtoken; the examples below have yourtoken as a placeholder.

Your first search

Replace yourtoken with your token, and spotify with what you want to find.

curl "https://api.opoint.com/search/" \
    -H "Authorization: Token yourtoken" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
    "searchterm": "spotify",
    "params": {
        "requestedarticles": 10,
        "groupidentical": 1,
        "main": {
            "header": 1,
            "summary": 1,
            "text": 1
        },
        "textrazor": 30975,
        "readership": 1
    }
}'

import requests

response = requests.post(
    "https://api.opoint.com/search/",
    headers={
        "Authorization": "Token yourtoken",
        "Accept": "application/json",
    },
    json={
        "searchterm": "spotify",
        "params": {
            "requestedarticles": 10,
            "groupidentical": 1,
            "main": {
                "header": 1,
                "summary": 1,
                "text": 1,
            },
            "textrazor": 30975,
            "readership": 1,
        },
    },
)
response.raise_for_status()

for article in response.json()["searchresult"]["document"]:
    print(article["header"]["text"])

const response = await fetch("https://api.opoint.com/search/", {
    method: "POST",
    headers: {
        "Authorization": "Token yourtoken",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "searchterm": "spotify",
        "params": {
            "requestedarticles": 10,
            "groupidentical": 1,
            "main": {
                "header": 1,
                "summary": 1,
                "text": 1
            },
            "textrazor": 30975,
            "readership": 1
        }
    }),
});

const { searchresult } = await response.json();
for (const article of searchresult.document) {
    console.log(article.header.text);
}

The search term can be more than a keyword: phrases, boolean expressions, and filters on language, country, sources and topics. See search syntax, or the guide to searching.

What the request asks for

Every param is optional. Params marked requires license only take effect if your account has that data licensed; without it, the request works but leaves that data out.

requestedarticles int, default 10

Number of articles to return.
groupidentical boolean

Group identical articles. If you enable this you will only receive one article from the group of identicals in your response. If you also enable include_ogae_identical you will also receive the identical articles in an array in identical_documents.
main object

Which parts of each article to return. All are off by default.

To get the full article text, set main.header, main.summary, and main.text to non-zero values.
textrazor int

error_outline Requires license
Add data about topics and entities to the response. The value is a bit field: add up the values of the options you want.

Topics and entities, added in a topics_and_entities field on each document:
- 1: IPTC topics
- 2: Entities
- 4: Entities without a Wikidata id
- 32768: Wikidata topics
Highlighting:
- 8: Adds entity ids to match tags (<match ent="1,23...">), plus wikinames and wikidescriptions dictionaries with the entities' names and descriptions. Match tags are enabled by main.matches, so set that too.
Company identifiers on entities:
- 2048: Crunchbase
- 4096: PermID
- 8192: LEI
- 16384: FIGI
Minimum topic score: to leave out weakly matching topics, add 16 × N, with N from 0 to 127. Topics scoring below N / 100 are then dropped; for example, adding 160 drops topics scoring below 0.10.

Some useful values:
- 30975: topics, entities, highlighting and company identifiers, with a minimum topic score of 0.15. A good starting point.
- 7: topics and entities without highlighting.
- 15: topics, entities and highlighting.
readership boolean

error_outline Requires license

Include similarweb.readership and similarweb.article_readership fields in the response, with readership estimates.

The response

The response is JSON, with the matching articles in searchresult.document. Here is one article, shortened:

{
  "searchresult": {
    "documents": 2,
    "count": 3,
    "context": "534348478:1:0;TOTDOC=2",
    "document": [
      {
        "id_site": 131,
        "id_article": 2122020,
        "unix_timestamp": 1613135182,
        "url": "http://redir.opoint.com/?url=https://www.bbc.com/news/uk-wales-56041927&OpointData=00224944d8c163c6dc90fd9e27cc7c3eJmlkX3NpdGU9MTMxJmlkX2FydGljbGU9MjEyMjAyMCZpZF91c2VyPTIyNDIyJmlkX2FwcGxpY2F0aW9uPTEwMDA0MTcmaWRfcGFydG5lcj0xJmxhbmc9ZW4=",
        "language": {
          "encoding": "iso-639",
          "text": "en"
        },
        "countrycode": "GB",
        "header": {
          "text": "Stonehenge: Did animals pull stones from Wales to England?"
        },
        "summary": {
          "text": "One of Britain's biggest and oldest stone circles has been found in Wales - and could be the original building blocks of Stonehenge."
        },
        "body": {
          "text": "<p> Archaeologists uncovered the remains of the Waun Mawn site in Pembrokeshire's Preseli Hills.</p> <p> They believe the stones could have been dismantled and …"
        },
        "similarweb": {
          "domain": "bbc.com",
          "readership": {
            "P": 0.012741,
            "value": 2162922
          }
        }
      }
    ]
  }
}

header, summary and body hold the text, because the request set main. The summary is often the article's first paragraph, not a recap, and the body continues after it, so you need all three for the full article. The header and summary are plain text; the body usually contains HTML.
topics_and_entities and similarweb hold the topics, entities and readership data, when your license includes them and there is data for the article.
context is where this batch ended. Pass it back to get the next batch; see next steps.

Every field is described in the search response reference.

Next steps

Paging and time windows are the usual next additions to the request:

context string

Pagination settings. Leave empty or out on the first search. Subsequent searches can use the value returned in the responses context field. If the returned value is non-empty, pass the value unchanged, along with the same search parameters, in order to fetch the next batch of results.
newest int, default 2147483647

Unix timestamp bounding the newest article to return.

When grouping articles, unless the strict_time_interval is set, the included articles can be outside of the time interval.
oldest int

Unix timestamp bounding the oldest article to return.

When grouping articles, unless the strict_time_interval is set, the included articles can be outside of the time interval.

Worked examples:

All params are listed in the search request reference.