Histograms
Show me this endpoint for

About

For the numerical metadata that the News API gathers (such as word counts or social shares for example), you can use the histograms endpoint to access and display this information.

As this endpoint does not return actual stories, the results you are given will not count towards your story allowance provided by your subscription, so you can effectively query this endpoint free of charge.

Parameters

Name Type Description Notes
id List<Long> This parameter is used for finding stories by story id. [optional]
notId List<Long> This parameter is used for excluding stories by story id. [optional]
title String This parameter is used for finding stories whose title contains a specfic keyword. It supports boolean operators. [optional]
body String This parameter is used for finding stories whose body contains a specfic keyword. It supports boolean operators. [optional]
text String This parameter is used for finding stories whose title or body contains a specfic keyword. It supports boolean operators. [optional]
language List<String> This parameter is used for finding stories whose language is the specified value. It supports ISO 639-1 language codes. [optional] [enum: en, de, fr, it, es, pt]
notLanguage List<String> This parameter is used for excluding stories whose language is the specified value. It supports ISO 639-1 language codes. [optional] [enum: en, de, fr, it, es, pt]
publishedAtStart String This parameter is used for finding stories whose published at time is greater than the specified value. Here you can find more information about how to work with dates. [optional]
publishedAtEnd String This parameter is used for finding stories whose published at time is less than the specified value. Here you can find more information about how to work with dates. [optional]
categoriesTaxonomy String This parameter is used for defining the type of the taxonomy for the rest of the categories queries. You can read more about working with categories here. [optional] [enum: iab-qag, iptc-subjectcode]
categoriesConfident Boolean This parameter is used for finding stories whose categories are confident. You can read more about working with categories here. [optional] [default to true]
categoriesId List<String> This parameter is used for finding stories by categories id. You can read more about working with categories here. [optional]
notCategoriesId List<String> This parameter is used for excluding stories by categories id. You can read more about working with categories here. [optional]
categoriesLevel List<Integer> This parameter is used for finding stories by categories level. You can read more about working with categories here. [optional]
notCategoriesLevel List<Integer> This parameter is used for excluding stories by categories level. You can read more about working with categories here. [optional]
entitiesTitleText List<String> This parameter is used to find stories based on the specified entities `text` in story titles. You can read more about working with entities here. [optional]
notEntitiesTitleText List<String> This parameter is used to exclude stories based on the specified entities `text` in story titles. You can read more about working with entities here. [optional]
entitiesTitleType List<String> This parameter is used to find stories based on the specified entities `type` in story titles. You can read more about working with entities here. [optional]
notEntitiesTitleType List<String> This parameter is used to exclude stories based on the specified entities `type` in story titles. You can read more about working with entities here. [optional]
entitiesTitleLinksDbpedia List<String> This parameter is used to find stories based on the specified entities dbpedia URL in story titles. You can read more about working with entities here. [optional]
notEntitiesTitleLinksDbpedia List<String> This parameter is used to exclude stories based on the specified entities dbpedia URL in story titles. You can read more about working with entities here. [optional]
entitiesBodyText List<String> This parameter is used to find stories based on the specified entities `text` in the body of stories. You can read more about working with entities here. [optional]
notEntitiesBodyText List<String> This parameter is used to exclude stories based on the specified entities `text` in the body of stories. You can read more about working with entities here. [optional]
entitiesBodyType List<String> This parameter is used to find stories based on the specified entities `type` in the body of stories. You can read more about working with entities here. [optional]
notEntitiesBodyType List<String> This parameter is used to exclude stories based on the specified entities `type` in the body of stories. You can read more about working with entities here. [optional]
entitiesBodyLinksDbpedia List<String> This parameter is used to find stories based on the specified entities dbpedia URL in the body of stories. You can read more about working with entities here. [optional]
notEntitiesBodyLinksDbpedia List<String> This parameter is used to exclude stories based on the specified entities dbpedia URL in the body of stories. You can read more about working with entities here. [optional]
sentimentTitlePolarity String This parameter is used for finding stories whose title sentiment is the specified value. [optional] [enum: positive, neutral, negative]
notSentimentTitlePolarity String This parameter is used for excluding stories whose title sentiment is the specified value. [optional] [enum: positive, neutral, negative]
sentimentBodyPolarity String This parameter is used for finding stories whose body sentiment is the specified value. [optional] [enum: positive, neutral, negative]
notSentimentBodyPolarity String This parameter is used for excluding stories whose body sentiment is the specified value. [optional] [enum: positive, neutral, negative]
mediaImagesCountMin Integer This parameter is used for finding stories whose number of images is greater than or equal to the specified value. [optional]
mediaImagesCountMax Integer This parameter is used for finding stories whose number of images is less than or equal to the specified value. [optional]
mediaImagesWidthMin Integer This parameter is used for finding stories whose width of images are greater than or equal to the specified value. [optional]
mediaImagesWidthMax Integer This parameter is used for finding stories whose width of images are less than or equal to the specified value. [optional]
mediaImagesHeightMin Integer This parameter is used for finding stories whose height of images are greater than or equal to the specified value. [optional]
mediaImagesHeightMax Integer This parameter is used for finding stories whose height of images are less than or equal to the specified value. [optional]
mediaImagesContentLengthMin Integer This parameter is used for finding stories whose images content length are greater than or equal to the specified value. [optional]
mediaImagesContentLengthMax Integer This parameter is used for finding stories whose images content length are less than or equal to the specified value. [optional]
mediaImagesFormat List<String> This parameter is used for finding stories whose images format are the specified value. [optional] [enum: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG]
notMediaImagesFormat List<String> This parameter is used for excluding stories whose images format are the specified value. [optional] [enum: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG]
mediaVideosCountMin Integer This parameter is used for finding stories whose number of videos is greater than or equal to the specified value. [optional]
mediaVideosCountMax Integer This parameter is used for finding stories whose number of videos is less than or equal to the specified value. [optional]
authorId List<Integer> This parameter is used for finding stories whose author id is the specified value. [optional]
notAuthorId List<Integer> This parameter is used for excluding stories whose author id is the specified value. [optional]
authorName String This parameter is used for finding stories whose author full name contains the specified value. [optional]
notAuthorName String This parameter is used for excluding stories whose author full name contains the specified value. [optional]
sourceId List<Integer> This parameter is used for finding stories whose source id is the specified value. [optional]
notSourceId List<Integer> This parameter is used for excluding stories whose source id is the specified value. [optional]
sourceName List<String> This parameter is used for finding stories whose source name contains the specified value. [optional]
notSourceName List<String> This parameter is used for excluding stories whose source name contains the specified value. [optional]
sourceDomain List<String> This parameter is used for finding stories whose source domain is the specified value. [optional]
notSourceDomain List<String> This parameter is used for excluding stories whose source domain is the specified value. [optional]
sourceLocationsCountry List<String> This parameter is used for finding stories whose source country is the specified value. It supports ISO 3166-1 alpha-2 country codes. Here you can find more information about how to work with locations. [optional]
notSourceLocationsCountry List<String> This parameter is used for excluding stories whose source country is the specified value. It supports ISO 3166-1 alpha-2 country codes. Here you can find more information about how to work with locations. [optional]
sourceLocationsState List<String> This parameter is used for finding stories whose source state/province is the specified value. Here you can find more information about how to work with locations. [optional]
notSourceLocationsState List<String> This parameter is used for excluding stories whose source state/province is the specified value. Here you can find more information about how to work with locations. [optional]
sourceLocationsCity List<String> This parameter is used for finding stories whose source city is the specified value. Here you can find more information about how to work with locations. [optional]
notSourceLocationsCity List<String> This parameter is used for excluding stories whose source city is the specified value. Here you can find more information about how to work with locations. [optional]
sourceScopesCountry List<String> This parameter is used for finding stories whose source scopes is the specified country value. It supports ISO 3166-1 alpha-2 country codes. Here you can find more information about how to work with locations. [optional]
notSourceScopesCountry List<String> This parameter is used for excluding stories whose source scopes is the specified country value. It supports ISO 3166-1 alpha-2 country codes. Here you can find more information about how to work with locations. [optional]
sourceScopesState List<String> This parameter is used for finding stories whose source scopes is the specified state/province value. Here you can find more information about how to work with locations. [optional]
notSourceScopesState List<String> This parameter is used for excluding stories whose source scopes is the specified state/province value. Here you can find more information about how to work with locations. [optional]
sourceScopesCity List<String> This parameter is used for finding stories whose source scopes is the specified city value. Here you can find more information about how to work with locations. [optional]
notSourceScopesCity List<String> This parameter is used for excluding stories whose source scopes is the specified city value. Here you can find more information about how to work with locations. [optional]
sourceScopesLevel List<String> This parameter is used for finding stories whose source scopes is the specified level value. Here you can find more information about how to work with locations. [optional] [enum: international, national, local]
notSourceScopesLevel List<String> This parameter is used for excluding stories whose source scopes is the specified level value. Here you can find more information about how to work with locations. [optional] [enum: international, national, local]
sourceLinksInCountMin Integer This parameter is used for finding stories from sources whose Links in count is greater than or equal to the specified value. You can read more about working with Links in count here. [optional]
sourceLinksInCountMax Integer This parameter is used for finding stories from sources whose Links in count is less than or equal to the specified value. You can read more about working with Links in count here. [optional]
sourceRankingsAlexaRankMin Integer This parameter is used for finding stories from sources whose Alexa rank is greater than or equal to the specified value. You can read more about working with Alexa ranks here. [optional]
sourceRankingsAlexaRankMax Integer This parameter is used for finding stories from sources whose Alexa rank is less than or equal to the specified value. You can read more about working with Alexa ranks here. [optional]
sourceRankingsAlexaCountry List<String> This parameter is used for finding stories from sources whose Alexa rank is in the specified country value. It supports ISO 3166-1 alpha-2 country codes. You can read more about working with Alexa ranks here. [optional]
socialSharesCountFacebookMin Integer This parameter is used for finding stories whose Facebook social shares count is greater than or equal to the specified value. [optional]
socialSharesCountFacebookMax Integer This parameter is used for finding stories whose Facebook social shares count is less than or equal to the specified value. [optional]
socialSharesCountGooglePlusMin Integer This parameter is used for finding stories whose Google+ social shares count is greater than or equal to the specified value. [optional]
socialSharesCountGooglePlusMax Integer This parameter is used for finding stories whose Google+ social shares count is less than or equal to the specified value. [optional]
socialSharesCountLinkedinMin Integer This parameter is used for finding stories whose LinkedIn social shares count is greater than or equal to the specified value. [optional]
socialSharesCountLinkedinMax Integer This parameter is used for finding stories whose LinkedIn social shares count is less than or equal to the specified value. [optional]
socialSharesCountRedditMin Integer This parameter is used for finding stories whose Reddit social shares count is greater than or equal to the specified value. [optional]
socialSharesCountRedditMax Integer This parameter is used for finding stories whose Reddit social shares count is less than or equal to the specified value. [optional]
intervalStart Integer This parameter is used for setting the start data point of histogram intervals. [optional]
intervalEnd Integer This parameter is used for setting the end data point of histogram intervals. [optional]
intervalWidth Integer This parameter is used for setting the width of histogram intervals. [optional]
field String This parameter is used for specifying the y-axis variable for the histogram. [optional] [default to social_shares_count] [enum: social_shares_count, social_shares_count.facebook, social_shares_count.linkedin, social_shares_count.reddit, social_shares_count.google_plus, characters_count, words_count, sentences_count, paragraphs_count, media.images.count, media.videos.count, source.links_in_count, source.rankings.alexa.rank, source.rankings.alexa.rank.COUNTRYCODE]

Return type

Histograms

Example

import com.aylien.newsapi.*;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import com.aylien.newsapi.parameters.*;
import com.aylien.newsapi.api.DefaultApi;

import java.util.Arrays;
import java.util.List;

public class Main {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: app_id
        ApiKeyAuth app_id = (ApiKeyAuth) defaultClient.getAuthentication("app_id");
        app_id.setApiKey("YOUR_APP_ID");

        // Configure API key authorization: app_key
        ApiKeyAuth app_key = (ApiKeyAuth) defaultClient.getAuthentication("app_key");
        app_key.setApiKey("YOUR_APP_KEY");

        DefaultApi apiInstance = new DefaultApi();

        List<Long> id = Arrays.asList(985744L);
        List<Long> notId = Arrays.asList(5241L, 4412L);
        String title = "startup AND (raise OR raised OR raising OR raises)";
        String body = "startup";
        String text = "startup company";
        List<String> language = Arrays.asList("en", "es", "es");
        List<String> notLanguage = Arrays.asList("fr", "pt", "it");
        String publishedAtStart = "NOW-3MONTHS/DAY";
        String publishedAtEnd = "NOW-10DAYS";
        String categoriesTaxonomy = "iab-qag";
        Boolean categoriesConfident = true;
        List<String> categoriesId = Arrays.asList("IAB15", "IAB13-1");
        List<String> notCategoriesId = Arrays.asList("IAB3-2");
        List<Integer> categoriesLevel = Arrays.asList(2);
        List<Integer> notCategoriesLevel = Arrays.asList(1, 3);
        List<String> entitiesTitleText = Arrays.asList("GNU/Linux", "Microsoft Windows");
        List<String> notEntitiesTitleText = Arrays.asList("Ireland", "Dublin");
        List<String> entitiesTitleType = Arrays.asList("Software", "Organization");
        List<String> notEntitiesTitleType = Arrays.asList("Agent", "Person");
        List<String> entitiesTitleLinksDbpedia = Arrays.asList("http://dbpedia.org/resource/Linux");
        List<String> notEntitiesTitleLinksDbpedia = Arrays.asList("http://dbpedia.org/resource/Windows");
        List<String> entitiesBodyText = Arrays.asList("GNU/Linux", "Microsoft Windows");
        List<String> notEntitiesBodyText = Arrays.asList("Trump");
        List<String> entitiesBodyType = Arrays.asList("Agent", "Person");
        List<String> notEntitiesBodyType = Arrays.asList("Software", "Organization");
        List<String> entitiesBodyLinksDbpedia = Arrays.asList("entitiesBodyLinksDbpedia_example");
        List<String> notEntitiesBodyLinksDbpedia = Arrays.asList("http://dbpedia.org/resource/Linux");
        String sentimentTitlePolarity = "negative";
        String notSentimentTitlePolarity = "positive";
        String sentimentBodyPolarity = "neutral";
        String notSentimentBodyPolarity = "negative";
        Integer mediaImagesCountMin = 2;
        Integer mediaImagesCountMax = 4;
        Integer mediaImagesWidthMin = 640;
        Integer mediaImagesWidthMax = 1024;
        Integer mediaImagesHeightMin = 480;
        Integer mediaImagesHeightMax = 800;
        Integer mediaImagesContentLengthMin = 25411;
        Integer mediaImagesContentLengthMax = 369541;
        List<String> mediaImagesFormat = Arrays.asList("JPEG", "BMP", "GIF");
        List<String> notMediaImagesFormat = Arrays.asList("PNG", "TIFF");
        Integer mediaVideosCountMin = 1;
        Integer mediaVideosCountMax = 2;
        List<Integer> authorId = Arrays.asList(36521);
        List<Integer> notAuthorId = Arrays.asList(2541);
        String authorName = "John Doe";
        String notAuthorName = "Mike Wally";
        List<Integer> sourceId = Arrays.asList(1411);
        List<Integer> notSourceId = Arrays.asList(251);
        List<String> sourceName = Arrays.asList("BBC");
        List<String> notSourceName = Arrays.asList("Fox News");
        List<String> sourceDomain = Arrays.asList("bbc.co.uk");
        List<String> notSourceDomain = Arrays.asList("foxnews.com");
        List<String> sourceLocationsCountry = Arrays.asList("US", "IE");
        List<String> notSourceLocationsCountry = Arrays.asList("IR");
        List<String> sourceLocationsState = Arrays.asList("California");
        List<String> notSourceLocationsState = Arrays.asList("Arizona");
        List<String> sourceLocationsCity = Arrays.asList("Los Angeles");
        List<String> notSourceLocationsCity = Arrays.asList("Dublin City");
        List<String> sourceScopesCountry = Arrays.asList("IE", "NG");
        List<String> notSourceScopesCountry = Arrays.asList("US", "GB");
        List<String> sourceScopesState = Arrays.asList("Co Dublin");
        List<String> notSourceScopesState = Arrays.asList("Co Wicklow");
        List<String> sourceScopesCity = Arrays.asList("Dublin City");
        List<String> notSourceScopesCity = Arrays.asList("Cork");
        List<String> sourceScopesLevel = Arrays.asList("national");
        List<String> notSourceScopesLevel = Arrays.asList("local");
        Integer sourceLinksInCountMin = 354211;
        Integer sourceLinksInCountMax = 587412;
        Integer sourceRankingsAlexaRankMin = 10;
        Integer sourceRankingsAlexaRankMax = 2500;
        List<String> sourceRankingsAlexaCountry = Arrays.asList("IE");
        Integer socialSharesCountFacebookMin = 3521;
        Integer socialSharesCountFacebookMax = 5841;
        Integer socialSharesCountGooglePlusMin = 2514;
        Integer socialSharesCountGooglePlusMax = 36521;
        Integer socialSharesCountLinkedinMin = 6521;
        Integer socialSharesCountLinkedinMax = 36521;
        Integer socialSharesCountRedditMin = 14125;
        Integer socialSharesCountRedditMax = 95412;
        Integer intervalStart = 2500;
        Integer intervalEnd = 200000;
        Integer intervalWidth = 2000;
        String field = "words_count";

        HistogramsParams.Builder histogramsBuilder = HistogramsParams.newBuilder();

        histogramsBuilder.setId(id);
        histogramsBuilder.setNotId(notId);
        histogramsBuilder.setTitle(title);
        histogramsBuilder.setBody(body);
        histogramsBuilder.setText(text);
        histogramsBuilder.setLanguage(language);
        histogramsBuilder.setNotLanguage(notLanguage);
        histogramsBuilder.setPublishedAtStart(publishedAtStart);
        histogramsBuilder.setPublishedAtEnd(publishedAtEnd);
        histogramsBuilder.setCategoriesTaxonomy(categoriesTaxonomy);
        histogramsBuilder.setCategoriesConfident(categoriesConfident);
        histogramsBuilder.setCategoriesId(categoriesId);
        histogramsBuilder.setNotCategoriesId(notCategoriesId);
        histogramsBuilder.setCategoriesLevel(categoriesLevel);
        histogramsBuilder.setNotCategoriesLevel(notCategoriesLevel);
        histogramsBuilder.setEntitiesTitleText(entitiesTitleText);
        histogramsBuilder.setNotEntitiesTitleText(notEntitiesTitleText);
        histogramsBuilder.setEntitiesTitleType(entitiesTitleType);
        histogramsBuilder.setNotEntitiesTitleType(notEntitiesTitleType);
        histogramsBuilder.setEntitiesTitleLinksDbpedia(entitiesTitleLinksDbpedia);
        histogramsBuilder.setNotEntitiesTitleLinksDbpedia(notEntitiesTitleLinksDbpedia);
        histogramsBuilder.setEntitiesBodyText(entitiesBodyText);
        histogramsBuilder.setNotEntitiesBodyText(notEntitiesBodyText);
        histogramsBuilder.setEntitiesBodyType(entitiesBodyType);
        histogramsBuilder.setNotEntitiesBodyType(notEntitiesBodyType);
        histogramsBuilder.setEntitiesBodyLinksDbpedia(entitiesBodyLinksDbpedia);
        histogramsBuilder.setNotEntitiesBodyLinksDbpedia(notEntitiesBodyLinksDbpedia);
        histogramsBuilder.setSentimentTitlePolarity(sentimentTitlePolarity);
        histogramsBuilder.setNotSentimentTitlePolarity(notSentimentTitlePolarity);
        histogramsBuilder.setSentimentBodyPolarity(sentimentBodyPolarity);
        histogramsBuilder.setNotSentimentBodyPolarity(notSentimentBodyPolarity);
        histogramsBuilder.setMediaImagesCountMin(mediaImagesCountMin);
        histogramsBuilder.setMediaImagesCountMax(mediaImagesCountMax);
        histogramsBuilder.setMediaImagesWidthMin(mediaImagesWidthMin);
        histogramsBuilder.setMediaImagesWidthMax(mediaImagesWidthMax);
        histogramsBuilder.setMediaImagesHeightMin(mediaImagesHeightMin);
        histogramsBuilder.setMediaImagesHeightMax(mediaImagesHeightMax);
        histogramsBuilder.setMediaImagesContentLengthMin(mediaImagesContentLengthMin);
        histogramsBuilder.setMediaImagesContentLengthMax(mediaImagesContentLengthMax);
        histogramsBuilder.setMediaImagesFormat(mediaImagesFormat);
        histogramsBuilder.setNotMediaImagesFormat(notMediaImagesFormat);
        histogramsBuilder.setMediaVideosCountMin(mediaVideosCountMin);
        histogramsBuilder.setMediaVideosCountMax(mediaVideosCountMax);
        histogramsBuilder.setAuthorId(authorId);
        histogramsBuilder.setNotAuthorId(notAuthorId);
        histogramsBuilder.setAuthorName(authorName);
        histogramsBuilder.setNotAuthorName(notAuthorName);
        histogramsBuilder.setSourceId(sourceId);
        histogramsBuilder.setNotSourceId(notSourceId);
        histogramsBuilder.setSourceName(sourceName);
        histogramsBuilder.setNotSourceName(notSourceName);
        histogramsBuilder.setSourceDomain(sourceDomain);
        histogramsBuilder.setNotSourceDomain(notSourceDomain);
        histogramsBuilder.setSourceLocationsCountry(sourceLocationsCountry);
        histogramsBuilder.setNotSourceLocationsCountry(notSourceLocationsCountry);
        histogramsBuilder.setSourceLocationsState(sourceLocationsState);
        histogramsBuilder.setNotSourceLocationsState(notSourceLocationsState);
        histogramsBuilder.setSourceLocationsCity(sourceLocationsCity);
        histogramsBuilder.setNotSourceLocationsCity(notSourceLocationsCity);
        histogramsBuilder.setSourceScopesCountry(sourceScopesCountry);
        histogramsBuilder.setNotSourceScopesCountry(notSourceScopesCountry);
        histogramsBuilder.setSourceScopesState(sourceScopesState);
        histogramsBuilder.setNotSourceScopesState(notSourceScopesState);
        histogramsBuilder.setSourceScopesCity(sourceScopesCity);
        histogramsBuilder.setNotSourceScopesCity(notSourceScopesCity);
        histogramsBuilder.setSourceScopesLevel(sourceScopesLevel);
        histogramsBuilder.setNotSourceScopesLevel(notSourceScopesLevel);
        histogramsBuilder.setSourceLinksInCountMin(sourceLinksInCountMin);
        histogramsBuilder.setSourceLinksInCountMax(sourceLinksInCountMax);
        histogramsBuilder.setSourceRankingsAlexaRankMin(sourceRankingsAlexaRankMin);
        histogramsBuilder.setSourceRankingsAlexaRankMax(sourceRankingsAlexaRankMax);
        histogramsBuilder.setSourceRankingsAlexaCountry(sourceRankingsAlexaCountry);
        histogramsBuilder.setSocialSharesCountFacebookMin(socialSharesCountFacebookMin);
        histogramsBuilder.setSocialSharesCountFacebookMax(socialSharesCountFacebookMax);
        histogramsBuilder.setSocialSharesCountGooglePlusMin(socialSharesCountGooglePlusMin);
        histogramsBuilder.setSocialSharesCountGooglePlusMax(socialSharesCountGooglePlusMax);
        histogramsBuilder.setSocialSharesCountLinkedinMin(socialSharesCountLinkedinMin);
        histogramsBuilder.setSocialSharesCountLinkedinMax(socialSharesCountLinkedinMax);
        histogramsBuilder.setSocialSharesCountRedditMin(socialSharesCountRedditMin);
        histogramsBuilder.setSocialSharesCountRedditMax(socialSharesCountRedditMax);
        histogramsBuilder.setIntervalStart(intervalStart);
        histogramsBuilder.setIntervalEnd(intervalEnd);
        histogramsBuilder.setIntervalWidth(intervalWidth);
        histogramsBuilder.setField(field);

        try {
            Histograms result = apiInstance.listHistograms(histogramsBuilder.build());
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#listHistograms");
            e.printStackTrace();
        }
    }
}