API reference

The API provides a RESTful interface to the Opoint database.

It returns JSON or XML-formatted responses, supports token based authentication, returns standard HTTP error codes, and follows a logical URI structure.

The base url is https://api.opoint.com. All requests should be sent over HTTPS.

Authorization

In order to use the API, you have to authorize your requests using your static token. This can be done in one of two ways: either using an Authorization header, or by supplying the token as a query parameter.

When using an Authorization header, add the keyword Token followed by the token value. The Token keyword indicates that you are authorizing using a token, and not say a username and a password.

You can test that your token works as it should, by sending a GET request to the APIs root: 

curl "https://api.opoint.com/" \
	-H "Authorization: Token yourtoken" \
	--include

If the response contains a 401 status code the authorization failed, and something was wrong with your token or how you wrote the header. In this case, you should expect to see a 403 error, which is fine, because you can't access data at the root.

Similarly, with the token as a query parameter: 

curl "https://api.opoint.com/?token=yourtoken" --include

StoredSearch

With the StoredSearch API you register searches that we match against newly crawled articles. The search hits are provided in a near real time feed, that you can either pull from, or that we deliver to you.

Searches can be registered and edited in M360, or directly in a RESTful fashion.

It is important to understand that although you can register multiple searches, all the hits are delivered in a single feed. Each stored search is assigned an id, and every document in the feed contains a stored_search_id, indicating which of the stored searches it matched.

  • GET /storedsearch/feed/

    Retrieve articles matching any of the stored searches, starting at the from parameter, searching forward in time.

    If you are continuously pulling data from the feed, a good strategy is to first pick an initial timestamp from where to get data.. Also decide on an interval.

    Then, make a request, passing the from and interval parameters. From the response, get the next_from field. This can be used as the from parameter in the next request to get the next batch of articles. Make sure to add some appropriate sleeping logic in between calls.

    Query parameters

    • link from required, int

      Unix timestamp to search from.

    • link to int

      Unix timestamp to search until.

    • link interval int, between 120 and 1800

      The number of seconds to search for, forward in time. If the ending time is in the future, the search will return content until the current time. Does not apply if to is set. If not provided, it will be set to 900 seconds.

    • link format json or xml

      Return format.

    • link num_art int, default 25000

      Maximum number of articles to return for each of the stored searches.

    • link topics int, 0 or 1

      Add a topics fields to the reponse.

    • link matches int, 0 or 1

      Mark search matches with <match> tags.

    • link equalgroup int, 0 or 1

      Add a equalgroup field to the response, with each articles group id.

    • link readership int
      error_outline Requires license

      Add readership data to the response. Please note that article level readership estimates can be uncertain when the article has just been published, as it is unclear for how long the article will stay visible. Updated readership estimates can be fetched from the search API.

    • link textrazor int
      error_outline Requires license

      Add textrazor data to the response. The parameter values are interpreted the same way as the search textrazor parameter.

    Response

    • link next_from int or missing

      Unix timestamp indicating where the current search stopped, and where the next one can start from. Only applies if interval is used.

    • link covered int or missing

      Difference between the from parameter and next_from. Can be negative if the from parameter was set to the future. Only applies if interval is used.

  • GET /storedsearch/

    List all of the stored searches. The endpoint uses pagination, and by default limits the results to 500.

    Query parameters

    • link limit int, default 500

      Maximum number of stored searches to return.

    • link offset int, default 0

      Skip the first stored searches, and return only results from offset and onwards.

  • POST /storedsearch/

    Add a new search to the list of stored searches.

    Request body

    • link access_group string
    • link get_old_articles boolean

      A boolean value to indicate if a historical search should be performed.

      Up to 25 000 articles from the past will be retrieved.

    • link max_age int

      Seconds back to search historically.

    • link use_syndicates boolean
      error_outline Requires license

      A boolean value to indicate whether the search should return generated syndicate articles.

  • GET /storedsearch/:id/

    Retrieve one of the stored searches.

    Response

    • link id int

      Id of the stored search, added to the results from the feed, such that the documents can be related to a stored search.

      It is also used to manipulate the stored search, updating or removing it.

    • link last_new_article int

      Unix timestamp of the last update to the stored search.

      An update is made whenever a new article comes in that matches the search. It can also update otherwise, but the timestamp will always be later than the last matching article.

    • link access_group object
      • link access_group.access_groups list of objects or missing
        • link access_groups[].name string or missing
        • link access_groups[].enabled boolean or missing
        • link access_groups[].value int or missing
      • link access_group.sites list of ints or missing
      • link access_group.sources list of ints or missing
    • link use_syndicates boolean or missing

      A boolean value to indicate whether the search should return generated syndicate articles.

  • PUT /storedsearch/:id/

    Update one of the stored searches.

    Request body

    • link access_group object
    • link get_old_articles boolean

      A boolean value to indicate if a historical search should be performed.

      Up to 25 000 articles from the past will be retrieved.

    • link max_age int

      Seconds back to search historically.

    • link use_syndicates boolean

      A boolean value to indicate whether the search should return generated syndicate articles.

  • DELETE /storedsearch/:id/

    Remove one of the stored searches.

Articles

  • POST /articles/readership/

    Fetch readership data for specific articles.

    The endpoint accepts an array of article identifiers and returns readership estimates including current readership, site-level readership, expected readership values, and suggested time to wait until next request.

    Request body

    • link id_site required, int

      Opoint site id

    • link id_article required, int

      Opoint article id

    Response

    • link id_site int

      Opoint site id

    • link id_article int

      Opoint article id

    • link readership int

      Current readership estimate for the article

    • link site_readership int

      Average readership estimate for the site

    • link expected_readership int

      Expected final readership estimate

    • link expected_next_day_readership int

      Expected readership estimate 24 hours from now

    • link first_seen int

      Unix timestamp when the article was first seen

    • link last_seen int

      Unix timestamp when the article was last seen

    • link active boolean

      Whether the article is currently visible on the website

    • link time_until_next_update int or missing

      Suggested time to wait until next request in seconds

Tracking

With the tracking service, you upload articles using FTP or the API, and get a feed containing new articles likely to mention the upload.

The matching articles contain a partner_article_id field, indicating which of the uploaded articles it is similar too, such that you can relate it to articles in your database.

Deliveries can be configured to include highlighting information about matches.

Results are typically delivered over FTP, but can also be accessed directly using the StoredSearch API.

  • POST /tracking/

    Upload an article to the database for tracking.

    Request body

    • link partner_article_id required, string

      A unique id identifying the article.

    • link title required, string

      Title of the article.

    • link summary string

      Lede of the article.

    • link text string

      Body text of the article.

    • link threshold int, between 15 and 100, default 20

      Only articles with a tracking score higher than the threshold will count as matches.

    • link duration int, between 1 and 30, default 30

      Number of days to look for matches.

    • link language string

      Language code of the language the article is written in. If not supplied, the language will be guessed.

    • link url string

      URL the article was published on.

    • link time required, string

      Time the article was published on the format YYYY-MM-DDThh:mm:ss.uuuuuuZ. If the time is in the future, it is truncated to the current time.

    Response

    • link id_site int

      Opoint site id of the created article.

    • link id_article int

      Opoint article id of the created article.

    Request body example

    {
  "title": "My news story",
  "summary": "This is the articles lede",
  "text": "Example text",
  "language": "en",
  "url": "https://mynewssite.com/articles/1/example.html",
  "time": "2020-06-14T12:00:04.00Z",
  "partner_article_id": "1"
}

  • POST /tracking/search/

    Retrieve information about uploaded articles using organization specific ids.

    You generally do not need to use this endpoint. The matches are fetched from the StoredSearch feed endpoint.

    Request body

    • link partner_article_ids required, list of strings

      List of organization ids. Duplicate ids will be removed. Ids are expected to match articles already uploaded.

    Request body example

    {
  "partner_article_ids": [
    "1",
    "2",
    "6"
  ]
}