API Response Structure

This page contains detailed information about the structure of the APITube API response, including description of all fields and their possible values.

General response structure

All APITube responses are returned in JSON format and have the following general structure:

{
    "status": "ok",
    "limit": 1,
    "path": "http://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1",
    "page": 1,
    "has_next_pages": true,
    "next_page": "http://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&page=2",
    "has_previous_page": false,
    "previous_page": "",
    "export": {
        "json": "http://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=json",
        "xlsx": "http://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=xlsx",
        "csv": "http://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=csv",
        "tsv": "http://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=tsv",
        "xml": "http://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=xml",
        "rss": "http://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=rss"
    },
    "request_id": "1044de7a-a39d-463c-b443-1d9141f7babe",
    "results": [
        // Array of articles
    ]
}

Main response fields

Field	Type	Description
status	string	Request status. Possible values: "ok" (request successful) or "error" (an error occurred).
limit	integer	Number of results per page (items per page).
path	string	Full URL of the current API request, including all request parameters.
page	integer	Current page of results.
has_next_pages	boolean	Flag indicating the presence of next pages of results (true - there are next pages).
next_page	string	Full URL to get the next page of results. Empty string if has_next_pages is false.
has_previous_page	boolean	Flag indicating the presence of previous pages of results (true - there are previous pages).
previous_page	string	Full URL to get the previous page of results. Empty string if has_previous_page is false.
export	object	Object with URLs for exporting results in various formats (json, xlsx, csv, tsv, xml, rss).
request_id	string	Unique request identifier for tracking and debugging.
results	array	Array with request results (articles).

Article object fields

Each article in the results array has the following structure:

{
    "id": "Unique article ID",
    "href": "URL of the original article",
    "published_at": "Publication date and time in ISO 8601 format",
    "title": "Article title",
    "description": "Brief article description",
    "body": "Full article text",
    "body_html": "Full article text with HTML formatting",
    "language": "Article language (ISO 639-1 code)",
    "author": {
        "id": "Author ID",
        "name": "Author name"
    },
    "image": "URL of the main article image",
    "categories": [
        {
            "id": "Category ID",
            "name": "Category name",
            "score": "Category relevance score for the article",
            "taxonomy": "Category taxonomy name",
            "links": {
                "self": "URL to get information about the category"
            }
        }
    ],
    "topics": [
        {
            "id": "Topic ID",
            "name": "Topic name",
            "score": "Topic relevance score for the article",
            "links": {
                "self": "URL to get information about the topic"
            }
        }
    ],
    "industries": [
        {
            "id": "Industry ID",
            "name": "Industry name",
            "links": {
                "self": "URL to get information about the industry"
            }
        }
    ],
    "entities": [
        {
            "id": "Entity ID",
            "name": "Entity name",
            "type": "Entity type (human, location, organization, brand, etc.)",
            "links": {
                "self": "URL to get information about the entity",
                "wikipedia": "Link to Wikipedia article",
                "wikidata": "Link to entity in Wikidata"
            },
            "frequency": "Frequency of entity mentions in the article",
            "title": {
                "pos": "Array of entity mention positions in the title"
            },
            "body": {
                "pos": "Array of entity mention positions in the article body"
            },
            "metadata": "Additional entity information (varies by entity type)"
        }
    ],
    "source": {
        "id": "Source ID",
        "domain": "Source domain",
        "home_page_url": "URL of the source homepage",
        "type": "Source type (news, blog, etc.)",
        "bias": "Source bias",
        "rankings": {
            "opr": "Source ranking"
        },
        "location": {
            "country_name": "Source country name",
            "country_code": "Source country code (ISO 3166-1 alpha-2)"
        },
        "favicon": "Source favicon URL"
    },
    "sentiment": {
        "overall": {
            "score": "Overall article sentiment score",
            "polarity": "Textual representation of sentiment (positive, negative, neutral)"
        },
        "title": {
            "score": "Title sentiment score",
            "polarity": "Textual representation of title sentiment"
        },
        "body": {
            "score": "Article body sentiment score",
            "polarity": "Textual representation of body sentiment"
        }
    },
    "summary": [
        {
            "sentence": "Key sentence from the article",
            "sentiment": {
                "score": "Sentence sentiment score",
                "polarity": "Textual representation of sentiment"
            }
        }
    ],
    "keywords": "Array of article keywords",
    "links": [
        {
            "url": "URL mentioned in the article",
            "type": "Link type (link, etc.)"
        }
    ],
    "media": [
        {
            "url": "Media file URL",
            "type": "Media file type (image, video, etc.)"
        }
    ],
    "story": {
        "id": "Story ID",
        "uri": "URL to get information about the story"
    },
    "is_duplicate": "Flag indicating if the article is a duplicate",
    "is_free": "Flag indicating if the article is freely available (not behind paywall)",
    "is_breaking": "Flag indicating if the article is breaking news",
    "read_time": "Estimated reading time in minutes",
    "sentences_count": "Number of sentences in the article",
    "paragraphs_count": "Number of paragraphs in the article",
    "words_count": "Number of words in the article",
    "characters_count": "Number of characters in the article"
}

Detailed description of article fields

Field	Type	Description
id	integer	Unique article identifier in the APITube system.
href	string	URL of the original article.
published_at	string	Date and time of article publication in ISO 8601 format.
title	string	Article headline.
description	string	Brief description or annotation of the article. May be absent for some articles.
body	string	Full article text without HTML tags.
body_html	string	Full article text with HTML formatting. May be absent for some articles.
language	string	Article language in ISO 639-1 format (two-letter code).
author	object	Information about the article author. The id field may be null if the author ID is not available.
image	string	URL of the main article image. May be absent for some articles.
categories	array	Array of categories the article belongs to.
topics	array	Array of topics related to the article with their relevance scores.
industries	array	Array of industries related to the article content.
entities	array	Array of objects with information about entities (people, places, organizations, etc.) mentioned in the article.
source	object	Information about the article source.
sentiment	object	Article sentiment assessment.
summary	array	Array of objects containing key sentences from the article with their sentiment assessment.
keywords	array	Array of keywords extracted from the article.
links	array	Array of objects with URLs mentioned in the article and their types.
media	array	Array of objects containing information about media files (images, videos) related to the article.
story	object	Information about the story the article belongs to (id and uri).
is_duplicate	boolean	Indicates if the article is a duplicate of another article.
is_free	boolean	Indicates if the article is freely available (not behind paywall).
is_breaking	boolean	Indicates if the article is breaking news.
read_time	integer	Estimated reading time in minutes.
sentences_count	integer	Number of sentences in the article.
paragraphs_count	integer	Number of paragraphs in the article.
words_count	integer	Number of words in the article.
characters_count	integer	Number of characters in the article.

Detailed description of nested objects

Category object

{
    "id": 258,
    "name": "exporting",
    "score": 0.6,
    "taxonomy": "iptc_mediatopics",
    "links": {
        "self": "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:20000366"
    }
}

Field	Type	Description
id	integer	Unique category identifier.
name	string	Category name.
score	float	Category relevance score for the article (from 0 to 1).
taxonomy	string	Name of the taxonomy the category belongs to.
links	object	Object with links related to the category.

Topic object

{
    "id": "market_news.commodities.potash",
    "name": "Potash Market News",
    "score": 0.2,
    "links": {
        "self": "https://api.apitube.io/v1/news/topic/market_news.commodities.potash"
    }
}

Field	Type	Description
id	string	Unique topic identifier.
name	string	Topic name.
score	float	Topic relevance score for the article (from 0 to 1).
links	object	Object with links related to the topic.

Industry object

{
    "id": 1067,
    "name": "Sporting event",
    "links": {
        "self": "https://api.apitube.io/v1/news/industry/1067"
    }
}

Field	Type	Description
id	integer	Unique industry identifier.
name	string	Industry name.
links	object	Object with links related to the industry.

Entity object

{
    "id": 1034399,
    "name": "Germany",
    "type": "location",
    "links": {
        "self": "https://api.apitube.io/v1/news/entity/1034399",
        "wikipedia": "https://en.wikipedia.org/wiki/Germany",
        "wikidata": "https://www.wikidata.org/wiki/Q183"
    },
    "frequency": 3,
    "title": {
        "pos": [{
            "start": 7,
            "end": 14
        }]
    },
    "body": {
        "pos": [
            {
                "start": 113,
                "end": 120
            },
            {
                "start": 852,
                "end": 859
            }
        ]
    },
    "metadata": {
        "name": "Germany",
        "type": "country",
        "aliases": ["Federal Republic of Germany"],
        "country": {
            "code": "DE",
            "name": "Germany"
        },
        "full_name": "Germany, Germany",
        "is_capital": false,
        "population": 83577140,
        "coordinates": {
            "lat": 51,
            "lng": 10
        },
        "description": "Country in Central Europe"
    }
}

Field	Type	Description
id	integer	Unique entity identifier.
name	string	Entity name.
type	string	Entity type (e.g., "human", "location", "organization", "brand").
links	object	Object with links to external resources related to the entity (API, Wikipedia, Wikidata).
frequency	integer	Frequency of entity mentions in the article.
title	object	Information about entity mention positions in the article title.
body	object	Information about entity mention positions in the article body.
metadata	object	Additional detailed information about the entity (varies by entity type).

Source object

{
    "id": 4232,
    "domain": "newsbytesapp.com",
    "home_page_url": "https://www.newsbytesapp.com",
    "type": "news",
    "bias": "right",
    "rankings": {
        "opr": 5
    },
    "location": {
        "country_name": "India",
        "country_code": "in"
    },
    "favicon": "https://www.google.com/s2/favicons?domain=https://www.newsbytesapp.com"
}

Field	Type	Description
id	integer	Unique source identifier.
domain	string	Source domain.
home_page_url	string	URL of the source homepage.
type	string	Source type (e.g., "news", "blog").
bias	string	Source bias (e.g., "left", "right", "center").
rankings	object	Source ratings and metrics.
location	object	Information about the geographic location of the source.
favicon	string	URL of the source favicon.

Author object

{
    "id": null,
    "name": ""
}

Field	Type	Description
id	integer	Author identifier. May be null if author ID is not available.
name	string	Author name. May be empty string if author name is not available.

Sentiment object

{
    "overall": {
        "score": -0.01,
        "polarity": "neutral"
    },
    "title": {
        "score": -0.09,
        "polarity": "negative"
    },
    "body": {
        "score": 0.07,
        "polarity": "positive"
    }
}

Field	Type	Description
overall	object	Overall article sentiment assessment.
title	object	Article title sentiment assessment.
body	object	Article body sentiment assessment.

Each sentiment object contains:

• score (float): numerical sentiment score (from -1 to 1, where negative values correspond to negative sentiment, and positive values to positive sentiment).
• polarity (string): textual representation of sentiment ("positive", "negative", "neutral").

Summary object

{
    "sentence": "an official said, highlighting the importance of this European nation in India",
    "sentiment": {
        "score": 0.17,
        "polarity": "positive"
    }
}

Field	Type	Description
sentence	string	Key sentence extracted from the article.
sentiment	object	Sentiment assessment for this specific sentence.

Story object

{
    "id": 3019419820,
    "uri": "https://api.apitube.io/v1/news/story/3019419820"
}

Field	Type	Description
id	integer	Unique story identifier.
uri	string	URL to get detailed information about the story via the API.

Links object

{
    "url": "https://www.newsbytesapp.com/news/world/belgium",
    "type": "link"
}

Field	Type	Description
url	string	URL mentioned in the article.
type	string	Link type (typically "link").

Media object

{
    "url": "https://i.cdn.newsbytesapp.com/images/l82720260111162041.jpeg",
    "type": "image"
}

Field	Type	Description
url	string	Media file URL.
type	string	Media file type (e.g., "image", "video").

Error response

In case of an error, the API returns a response with status "401" and additional information about the error:

{
  "status": 401,
  "code": "ER0175",
  "message": "Your API key is invalid or missing.",
  "links": {
      "about": "https://docs.apitube.io/platform/news-api/http-response-codes"
  }
}

Field	Type	Description
status	integer	HTTP status code of the error.
code	string	Error code. Used for programmatic error handling.
message	string	Human-readable error message.
links	object	Object with links to documentation about the error.

Error codes

Code	HTTP status	Description
invalid_api_key	401	Invalid or missing API key.
unauthorized	401	Insufficient permissions to perform the request.
quota_exceeded	429	Request limit exceeded.
invalid_parameter	400	Invalid parameter value.
missing_parameter	400	Missing required parameter.
internal_error	500	Internal server error.

Pagination

For working with large datasets, the API uses pagination. By default, the first page of results is returned. To access other pages, use the page and per_page parameters. The limit field in the response shows the number of items per page.

Example of pagination request:

https://api.apitube.io/v1/news/everything?title=technology&page=2&per_page=20

Response with pagination information:

{
  "status": "ok",
  "limit": 20,
  "path": "https://api.apitube.io/v1/news/everything?title=technology&page=2&per_page=20",
  "page": 2,
  "has_next_pages": true,
  "next_page": "https://api.apitube.io/v1/news/everything?title=technology&page=3&per_page=20",
  "has_previous_page": true,
  "previous_page": "https://api.apitube.io/v1/news/everything?title=technology&page=1&per_page=20",
  "results": [
    // Article objects
  ]
}

API response example

{
  "status": "ok",
  "limit": 2,
  "path": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1",
  "page": 1,
  "has_next_pages": true,
  "next_page": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=2",
  "has_previous_page": false,
  "previous_page": "",
  "export": {
    "json": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=json",
    "xlsx": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=xlsx",
    "csv": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=csv",
    "tsv": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=tsv",
    "xml": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=xml",
    "rss": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=rss"
  },
  "request_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "results": [
    {
      "id": 12345678,
      "href": "https://example.com/tech/new-smartphone-release",
      "published_at": "2023-06-15T10:30:00Z",
      "title": "New XYZ Smartphone Makes Waves in the Market",
      "description": "XYZ Company has introduced a new flagship smartphone that significantly outperforms competitors in performance and camera quality.",
      "body": "Today, XYZ Company introduced its new flagship smartphone. The device is equipped with the latest generation processor and a revolutionary camera that, according to the manufacturer, is capable of taking professional quality photos even in low light conditions. Industry experts have already highly rated the novelty, noting its excellent performance and innovative features.",
      "body_html": "<p>Today, XYZ Company introduced its new flagship smartphone. The device is equipped with the latest generation processor and a revolutionary camera that, according to the manufacturer, is capable of taking professional quality photos even in low light conditions. Industry experts have already highly rated the novelty, noting its excellent performance and innovative features.</p>",
      "language": "en",
      "author": {
        "id": 5678,
        "name": "John Smith"
      },
      "image": "https://example.com/images/xyz-smartphone.jpg",
      "categories": [
        {
          "id": 199,
          "name": "economy, business and finance",
          "score": 0.6,
          "taxonomy": "iptc_mediatopics",
          "links": {
            "self": "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:04000000"
          }
        }
      ],
      "topics": [
        {
          "id": "industry.financial_news",
          "name": "Finance Industry News",
          "score": 0.1,
          "links": {
            "self": "https://api.apitube.io/v1/news/topic/industry.financial_news"
          }
        }
      ],
      "industries": [
        {
          "id": 456,
          "name": "Consumer Electronics",
          "links": {
            "self": "https://api.apitube.io/v1/news/industry/456"
          }
        }
      ],
      "entities": [
        {
          "id": 789,
          "name": "XYZ Company",
          "type": "organization",
          "links": {
            "self": "https://api.apitube.io/v1/news/entity/789",
            "wikipedia": "https://en.wikipedia.org/wiki/XYZ_Company",
            "wikidata": "https://www.wikidata.org/wiki/Q12345"
          },
          "frequency": 3,
          "title": {
            "pos": [
              {
                "start": 4,
                "end": 15
              }
            ]
          },
          "body": {
            "pos": [
              {
                "start": 6,
                "end": 17
              },
              {
                "start": 122,
                "end": 133
              }
            ]
          },
          "metadata": {
            "name": "XYZ Company",
            "type": "business",
            "country": {
              "code": "US",
              "name": "United States"
            },
            "description": "Technology company"
          }
        }
      ],
      "source": {
        "id": 123,
        "domain": "example.com",
        "home_page_url": "https://example.com",
        "type": "news",
        "bias": "center",
        "rankings": {
          "opr": 8
        },
        "location": {
          "country_name": "United States",
          "country_code": "us"
        },
        "favicon": "https://example.com/favicon.ico"
      },
      "sentiment": {
        "overall": {
          "score": 0.45,
          "polarity": "positive"
        },
        "title": {
          "score": 0.3,
          "polarity": "positive"
        },
        "body": {
          "score": 0.6,
          "polarity": "positive"
        }
      },
      "summary": [
        {
          "sentence": "Today, XYZ Company introduced its new flagship smartphone.",
          "sentiment": {
            "score": 0.2,
            "polarity": "positive"
          }
        },
        {
          "sentence": "Industry experts have already highly rated the novelty, noting its excellent performance and innovative features.",
          "sentiment": {
            "score": 0.8,
            "polarity": "positive"
          }
        }
      ],
      "keywords": ["smartphone", "XYZ", "technology"],
      "links": [
        {
          "url": "https://example.com/related/xyz-previous-model",
          "type": "link"
        }
      ],
      "media": [
        {
          "url": "https://example.com/images/xyz-smartphone.jpg",
          "type": "image"
        },
        {
          "url": "https://example.com/videos/xyz-smartphone-preview.mp4",
          "type": "video"
        }
      ],
      "story": {
        "id": 9876,
        "uri": "https://api.apitube.io/v1/news/story/9876"
      },
      "is_duplicate": false,
      "is_free": true,
      "is_breaking": false,
      "read_time": 2,
      "sentences_count": 3,
      "paragraphs_count": 1,
      "words_count": 60,
      "characters_count": 354
    }
  ]
}

Notes

1. Field availability: Some fields may be absent from the response depending on data availability for a specific article or the subscription plan used.

2. Date format: All dates in the API are returned in ISO 8601 format (e.g., "2023-06-15T10:30:00Z").

3. Content limitations: Depending on the subscription plan, the body and body_html fields may contain the full text of the article or only a part of it.

4. Language and country: The language and country fields use standard ISO codes (ISO 639-1 for languages and ISO 3166-1 alpha-2 for countries).

5. Sentiment: The score value ranges from -1 to 1, where negative values correspond to negative sentiment, and positive values to positive sentiment.

6. Entity metadata: The metadata field in entity objects provides detailed information about the entity. The structure and available fields vary depending on the entity type (location, organization, brand, etc.).