Data models

When making queries in Event Registry, there are different data types that are returned as JSON objects, such as information about an event, article, concept, category, etc. The amount of details returned for each data type depends on the provided flags specified in the ReturnInfo class instance. Below we will provide data models for common data types together with all possible fields.

Article data model

Available details about an article.

{
    // article's URI (unique article's ID - not necessarily a number)
    "uri": "143701955",
    // web url
    "url": "http://www.Newsmax.com/Newsfront/obama-staff-veterans-revamp/2013/12/18/id/542478",
    // article's title
    "title": "Desperate Obama Tries to Reset Agenda with New Staff",
    // article's full body
    "body": "Highlight the link and press CTRL/Command + C to copy the link to your clipboard.\n As Phil Schiliro arrived at his first meeting last ...",
    // date and time of publishing in UTC timezone
    "date": "2013-12-18",
    "time": "11:40:00",
    // when was the article serialized. Each next article added to Event Registry has to have a higher value
    "dateTime": "2013-12-18T11:40:00Z",
    // when was the article first discovered in the RSS feeds. Value is closer to the actual time when the article was published, but the value is not monotonically increasing as the articles are added to Event Registry
    "dateTimePub": "2013-12-18T11:12:00Z",
    // type of the article (news, blog, pr)
    "dataType": "news",
    // sentiment of the article (can be null if value is not set). Between -1 and 1.
    "sentiment": -0.2,
    // event URI to which the article is assigned to (if any)
    "eventUri": "20588",
    // relevance represents how well does the article match the query - the higher the value, the better the match.
    // If search results are sorted by relevance, this is the value used for sorting
    "relevance": 34,
    // cluster/story URI to which the article is assigned to (if any)
    "storyUri": "850f305d-14db-4c75-b547-79470a557ea3-4134",
    "source": {
        // details about the news source (see Source data model)
    },
    "categories": [
        // list of categories (see Category data model)
    ],
    "concepts": [
        // list of concepts (see Concept data model)
    ],
    "links": [
        "https://techcrunch.com/2017/11/29/coinbase-internal-revenue-service-taxation/",
        ...
    ],
    "videos": [
        {
            "uri": "https://www.youtube.com/embed/Phtb6nZWiW0",
            "label": "GoPro on a Cat Left Home Alone"
        },
        ...
    ],
    // article's image
    "image": "https://cdn.arstechnica.net/wp-content/uploads/2013/07/you-slow.jpg",
    // if an article is a duplicate, this list will contain them
    "duplicateList": [],
    // dates that were extracted from the article
    "extractedDates": [
        {
            "amb": false,               // ambiguous?
            "date": "2013-12-03",       // normalized date
            "dateEnd": "2013-12-08",
            "detectedDate": "Dec. 3-8", // detected string
            "imp": true,                // was the year value imputed?
            "posInText": 6164,          // location in text
            "textSnippet": "ublican attacks.  A Dec. 3-8 poll of 86 competit"
        },
        // remaining list of extracted dates
    ],
    "isDuplicate": false,       // is article a duplicate of another article?
    "lang": "eng",              // language of the article
    "location": null,           // was there explicit location extracted from dateline?
    "originalArticle": null,    // if this is a duplicate, this would be original article's object
    "sim": 0.3906,              // cosine similarity of the article to the centroid of the story
    "wgt": 12341243,            // parameter used internally for sorting purposes (DO NOT USE THE VALUE)
    "shares": {
        "facebook": 1,          // number of shares on Facebook
        "googlePlus": 5,        // shares on Google Plus
        "pinterest:" 2,         // shares on Pinterest
        "linkedIn": 1           // shares on LinkedIn
    }
}

Event data model

Available details about an event.

{
    // event URI
    "uri": "3403979",
    // total articles reporting about the event
    "totalArticleCount": 100,
    // articles per language
    "articleCounts": {
        "deu": 82,
        "eng": 18
    },
    "concepts": [
        // list of concepts (see Concept data model)
    ],
    "categories": [
        // list of categories (see Category data model)
    ],
    // event title in available languages
    "title": {
        "deu": "Obama kommt zur Er\u00f6ffnung der Hannover Messe",
        "eng": "White House says Obama will make 5th visit to Germany, take in trade show"
    },
    // event summary in available languages
    "summary": {
        "deu": "Hannover (dpa) US-Pr\u00e4sident Obama kommt 2016 wieder nach Deutschland: In Hannover er\u00f6ffnet er die weltgr\u00f6\u00dfte Industrieschau. Die Sicherheitsma\u00dfnahmen werden sch\u00e4rfer sein als 2013. Damals war Russlands Pr\u00e4sident Putin beim Er\u00f6ffnungs-Rundgang von halbnackten Frauen best\u00fcrmt worden.\n\nBarack Obama besucht zum f\u00fcnften mal als US-Pr\u00e4sident Deutschland. Am 24. April 2016 will er zusammen mit Kanzlerin Angela Merkel (CDU) die weltgr\u00f6\u00dfte Industrieschau Hannover Messe er\u00f6ffnen. Die USA sind",
        "eng": "HONOLULU, Hawaii - The White House says President Barack Obama will travel to Germany in late April to attend the world's largest trade show for industrial technology.\n\nObama will also meet with Germany Chancellor Angela Merkel in what will be his fifth trip to that nation.\n\nThe White House is describing the trip as a chance for Obama to highlight the U.S. as a prime investment destination for the 6,500 exhibitors who attend the Hannover Messe. He will be the first sitting president to attend the"
    },
    // which dates have been frequently found in articles about this event
    "commonDates": [
        {
            "date": "2016-04-24",
            "freq": 11
        },
        // remaining common dates
    ],
    // when the event happened
    "eventDate": "2016-04-24",
    // sentiment of the event (can be null if value is not set). Between -1 and 1.
    "sentiment": -0.2,
    // how much impact on social media did articles about the event get
    "socialScore": 91.4,
    "wgt": 12341243,            // parameter used internally for sorting purposes
    // images about the event
    "images": [
        "https://s.yimg.com/iu/api/res/1.2/6UFJrRnyw2A6g2AluS0rsw--/YXBwaWQ9eXZpZGVvO2ZpPXVsY3JvcDt3PTY5NjtoPTM1NDtkeD0xO2R5PTE7Y3c9NTExO2NoPTI4ODtxPTcwO249MTtyb3RhdGU9YXV0bw--/https://s.yimg.com/ea/img/-/151231/9c2c262efe2356511db7197c9881586532ebe450-1b88bu9.jpg",
        "http://www.usnews.com/cmsmedia/60/1b7fa9a9715152863ace8d91f7a8f5/media:b89ea0bb94754cb9bce137c9e9f7fd0bObama.JPEG"
    ],
    // where did the event happen
    "location": {
        "country": {
            "area": 357021,
            "code2": "DE",
            "code3": "DEU",
            "continent": "Europe",
            "currencyCode": "EUR",
            "currencyName": "Euro",
            "geoNamesId": "2921044",
            "label": {
                "eng": "Germany",
                "spa": "Alemania"
            },
            "lat": 51.5,
            "long": 10.5,
            "population": 81802257,
            "type": "country",
            "webExt": ".de",
            "wikiUri": "http://en.wikipedia.org/wiki/Germany"
        },
        "featureCode": "P.PPLA",
        "geoNamesId": "2910831",
        "label": {
            "eng": "Hanover",
            "spa": "Hannover"
        },
        "lat": 52.37052,
        "long": 9.73322,
        "population": 515140,
        "type": "place",
        "wikiUri": "http://en.wikipedia.org/wiki/Hanover"
    },
    "stories": [
        // list of clusters reporting about the event
    ]
}

Concept data model

Events and articles can be associated with a list of concepts. For each concept, here is a list of available details:

{
    // concept's URI
    "uri": "http://en.wikipedia.org/wiki/United_States",
    // concept type - person, loc, org or wiki
    "type": "loc",
    // image of the concept
    "image": "http://upload.wikimedia.org/wikipedia/commons/thumb/0/03/USA-satellite.jpg/1280px-USA-satellite.jpg",
    // concept labels in requested languages
    "label": {
        "eng": "United States",
        "spa": "Estados Unidos"
    },
    // what classes does the concept belong to
    "conceptClassMembership": [
        "http://dbpedia.org/ontology/Country"
    ],
    // if concept is a location, below are location details
    "location": {
        "area": 9629091,
        "code2": "US",
        "code3": "USA",
        "continent": "Noth America",
        "currencyCode": "USD",
        "currencyName": "Dollar",
        "geoNamesId": "6252001",
        "label": {
            "eng": "United States",
            "spa": "Estados Unidos"
        },
        "lat": 39.76,
        "long": -98.5,
        "population": 310232863,
        "type": "country",
        "webExt": ".us",
        "wikiUri": "http://en.wikipedia.org/wiki/United_States"
    },
    // synonyms for the concept, if any
    "synonyms": {
        "eng": [
            "USA",
            "U.S.A."
        ]
    }
}

Category data model

Articles and events are associated with one or more categories. Here are the possible details provided for a category.

{
    // category's URI
    "uri": "dmoz/Society/Issues/Warfare_and_Conflict",
    // URI of the parent category
    "parentUri": "dmoz/Society/Issues",
    // category label
    "label": "Society/Issues/Warfare_and_Conflict"
}

News source data model

News articles are associated with a news source. Below is the available information about a news source.

{
    // URI of the news source
    "uri": "bbc.co.uk"
    // title
    "title": "BBC News",
    // total nr. of articles from this source
    "articleCount": 266228,
    "description": "",
    // social media accounts of the media
    "socialMedia": {
        "twitter": "BBCNews"
    },
    "ranking": {
          "importanceRank": 23,         // importance of the source (in range 0-100, low value -> high importance)
          "alexaGlobalRank": 123412,    // global ranking of the website based on Amazon Alexa
          "alexaCountryRank": 412       // country level ranking of the website based on Amazon Alexa
    },
    // geographical location of the source
    "location": {
        "country": {
            "area": 244820,
            "code2": "GB",
            "code3": "GBR",
            "continent": "Europe",
            "currencyCode": "GBP",
            "currencyName": "Pound",
            "geoNamesId": "2635167",
            "label": {
                "spa": "Reino Unido"
            },
            "lat": 54.75844,
            "long": -2.69531,
            "population": 62348447,
            "type": "country",
            "webExt": ".uk",
            "wikiUri": "http://en.wikipedia.org/wiki/United_Kingdom"
        },
        "featureCode": "P.PPLC",
        "geoNamesId": "2643743",
        "label": {
            "spa": "Londres"
        },
        "lat": 51.50853,
        "long": -0.12574,
        "population": 7556900,
        "type": "place",
        "wikiUri": "http://en.wikipedia.org/wiki/London"
    },
    "sourceGroup": [],
    // source images
    "image": "http://www.some-larger-logo-for-the-source.png",
    "thumbImage": "http://www.some-small-logo-for-the-source.png"
}