Few inconsistencies in documentation

[pkese]

Here are a few ideas on how documentation could be improved...

Stories 1

Stories are often referred to, but never defined, making it unclear what a story represents: https://www.newsapi.ai/documentation?tab=terminology
They appear to be some sort of clusters, but are they clusters of articles within an event or a clusters of events within some wider scope.
Are stories somehow related to a longer time span? Are events points in time?

Stories 2

Also storyUri is inconsistently defined:

• present in data model example
• absent in articles output schema

Videos

Videos are also inconsistently defined:

• in article otuput schema as array of strings

    "videos": {
        "type": "array",
        "items": {
            "type": "string"
        }
    }

• in data model example as array of objects

    // list of videos extracted from the body
    "videos": [
        {
            "uri": "https://www.youtube.com/embed/Phtb6nZWiW0",
            "label": "GoPro on a Cat Left Home Alone"
        },
        ...
    ],

[gregorleban]

Hi Peter,

yes, stories are intentionally not clarified as it would introduce more confusion for the regular users.

The details are as follows:

• we collect news articles
• articles are grouped into clusters, which are actually what in our terminology would be stories. Stories are groups of news articles in a single language that have very similar content
• on top of the stories we also potentially group stories across the languages (and sometimes even inside the same language) if a model decides that the crosslingual similarity is high enough and the concept fingerprint is similar enough. This is what we then call an event. An event is therefore a group of stories (where each has a number of articles) that in our opinion talk about the same hapening.

In practice, you don't really have a reason why you'd want to use the stories directly. If you just want articles in a single language, you can filter them using a filter in QueryEvent.

If someone really needs, there is also a class QueryStory, where you can actually query for stories, as you otherwise can also query for events.

Thank you for finding the discrepancy about the videos. We'll update the documentation.

Btw, as you can guess, this repo is not something that we maintain and we'll remove it very soon. If you'll have any other issues/comments I suggest that you post them here: https://github.com/EventRegistry/event-registry-python/

Best,
Gregor