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 (newsfeed id)
    "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
    "date": "2013-12-18",
    "time": "11:40:00",
    "datetime": "2013-12-18T11:40:00Z",
    // sentiment of the article (can be null if value is not set)
    "sentiment": -0.2,
    // event URI to which the article is assigned to (if any)
    "eventUri": "20588",
    // 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
    ],
    "id": "565",                // internal ER id - do not use!
    "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
    "shares": {
        "facebook": 1,          // number of shares on Facebook
        "twitter": 17,          // number of shares on Twitter
        "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",
    // how much impact on social media did articles about the event get
    "socialScore": 91.4,
    // 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
    ],
    // if event is provided as a result of a query, wgt represent relevance to the query (in range 0-100)
    "wgt": 98
}

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."
        ]
    },
    // mentions of the concept in articles in previous days
    "trendingHistory": {
        "latestArticleTimestamp": "2016-03-17 03:44:00",
        "news": [
            43205,
            47421,
            42268,
            24571,
            23592,
            40801,
            46281,
            44131,
            42349,
            40098,
            22493,
            19931,
            35973,
            39301,
            41055,
            37807,
            37715,
            21093,
            19600,
            33415,
            33991,
            37013,
            35453,
            34549,
            21207,
            19163,
            33015,
            35504,
            36670,
            5124
        ]
    },
    // how much is the concept currently trending in the news
    "trendingScore": {
        "news": {
            "nullPopFq": 440580,
            "score": 5.157707577282254,
            "testPopFq": 41794
        }
    },
    // textual description of the concept
    "description": "<p>The United States of America (USA), commonly referred to as the United States (U.S.), America, and sometimes the States, is a federal republic consisting of 50 states, 16 territories, and a federal district. The 48 contiguous states and Washington, D.C., are in central North America between Canada and Mexico. The state of Alaska is located in the northwestern part of North America and the state of Hawaii is an archipelago in the mid-Pacific.</p>",
    // internal ER id - do not use
    "id": "233"
}

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",
    // URIs of children categories
    "childrenUris": [],
    // how much was the category trending in the last days
    "trendingHistory": {
        "latestArticleTimestamp": "2016-03-17 03:44:00",
        "news": [
            5867,   // 29 days ago
            6818,
            5927,
            3056,
            3027,
            5469,
            6075,
            5296,
            5289,
            5313,
            3322,
            2842,
            4606,
            5202,
            5062,
            4820,
            5001,
            2427,
            2962,
            5457,
            5423,
            5724,
            5152,
            4848,
            2886,
            3371,
            5957,
            5782,   // 2 days ago
            5139,   // yesterday
            646     // today
        ]
    },
    // trending score of the category
    "trendingScore": {
        "news": {
            "nullPopFq": 64872,
            "score": -3.386597994967876,
            "testPopFq": 5785
        }
    },
    // internal ER id - do not use!
    "id": 283
}

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",
    // internal ER id - do not use
    "id": "1017"
}