Modules Documentation¶

The pypresseportal module¶

The `PresseportalApi` class¶

class pypresseportal.PresseportalApi(api_key: str)¶

A Python interface into the presseportal.de API.

The website presseportal.de is a service provided by ‘news aktuell’, owned by dpa (Deutsche Presse Agentur). An API key from presseportal.de is required. You can find more information and apply for an API key at https://api.presseportal.de/en. The documentation for PyPresseportal is at https://pypresseportal.readthedocs.io/.

First, create an instance of the PresseportalApi class, using your API key:

>>> from pypresseportal import PresseportalApi
>>> api_object = PresseportalApi(YOUR_API_KEY)

Next, request data from the API, using the various methods in this class.

For example:

Use the method get_stories() to access the most recently published stories (https://api.presseportal.de/doc/article/all). If no arguments are provided, PyPresseportal defaults to retrieving the 50 most recent stories available. For example:

>>> stories = api_object.get_stories()

Story data can be accessed through the individual Story object’s attributes. For example:

>>> stories[0].title
"Kohls Wohnhaus hat keinen Denkmalwert"
>>> stories[0].id
"4622388"

get_company_information(id: str) → pypresseportal.pypresseportal.Company¶

Queries API for detailed information about a specific company.

Returns a pypresseportal.Company object. More information: https://api.presseportal.de/doc/info/company/id

Parameters

id (str) – id of company (read Entity.id of a get_entity_search_results() search for this id).

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.

Returns

An object containing details about the requested company.

Return type

Company

get_entity_search_results(search_term: Union[str, List[str]], entity: str = 'company', limit: int = 20) → Optional[List[pypresseportal.pypresseportal.Entity]]¶

Search for company or public service office by location or name.

Returns a list of pypresseportal.Entity objects. More information: https://api.presseportal.de/doc/search/company

Parameters

search_term (Union[str, List[str]]) – One or multiple search terms (min 3 chars.).
entity (str, optional) – Search for ‘office’ or ‘company’. Defaults to “company”.
limit (int, optional) – Limit number of objects in response (API maximum is 20). Defaults to 20.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
SearchTermError – Api does not support the requested search term.
SearchEntityError – Api does not support the requested entity.

Returns

List of Entity objects. None if nothing found.

Return type

Union[List[Entity], None]

get_investor_relations_news(news_type: str = 'all', start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for most recent investor relations press releases.

Returns a list of pypresseportal.Story objects. More information: https://api.presseportal.de/doc/ir/list

Parameters

news_type (str, optional) – Investor relations news type (https://api.presseportal.de/doc/value/ir_type). Defaults to “all”.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
NewsTypeError – API does not support the requested news type.

Returns

List of Story objects

Return type

List[Story]

get_investor_relations_news_company(id: str, news_type: str = 'all', start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for investor relations press releases of a specific company.

Returns a list of pypresseportal.Story objects. More information: https://api.presseportal.de/doc/ir/company/id/list

Parameters

id (str) – id of company (read Entity.id of a get_entity_search_results() search for this id).
news_type (str, optional) – Investor relations news type (https://api.presseportal.de/doc/value/ir_type). Defaults to “all”.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
NewsTypeError – API does not support the requested news type.

Returns

List of Story objects

Return type

List[Story]

get_public_service_news(media: str = None, start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for public service news (police and fire departments, etc.).

Returns a list of pypresseportal.Story objects. More information: https://api.presseportal.de/doc/article/publicservice.

Parameters

media (str, optional) – Only request stories containing this specific media type (image or document). Defaults to None.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
MediaError – API does not support the requested media type.

Returns

List of Story objects

Return type

List[Story]

get_public_service_office_information(id: str) → pypresseportal.pypresseportal.Office¶

Queries API for detailed information about a specific public service office (police or fire department, etc.).

Returns a pypresseportal.Office object. More information: https://api.presseportal.de/doc/info/office/id

Parameters

id (str) – id of office (read Entity.id of a get_entity_search_results() search for this id).

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.

Returns

An object containing details about the requested office.

Return type

Office

get_public_service_specific_office(id: str, media: str = None, start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for stories released by a specific public service office.

Returns a list of pypresseportal.Story objects. More information: https://api.presseportal.de/doc/article/publicservice/office/id

Parameters

id (str) – id of office (read Entity.id of a get_entity_search_results() search for this id).
media (str, optional) – Only request stories containing this specific media type (image or document). Defaults to None.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
MediaError – API does not support the requested media type.

Returns

List of Story objects

Return type

List[Story]

get_public_service_specific_region(region_code: str, media: str = None, start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for stories by public service offices in a specific region.

Returns a list of pypresseportal.Story objects. List of region codes and more information: https://api.presseportal.de/doc/article/publicservice/region.

Parameters

region_code (str) – Only request stories located in this specific region.
media (str, optional) – Only request stories containing this specific media type (image or document). Defaults to None.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
MediaError – API does not support the requested media type.
RegionError – API does not support the requested region code.

Returns

List of Story objects

Return type

List[Story]

get_stories(media: str = None, start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for most recent press releases.

Returns a list of pypresseportal.Story objects. More information: https://api.presseportal.de/doc/article/all.

Parameters

media (str, optional) – Only request stories containing this specific media type (image, document, audio or video). Defaults to None.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
MediaError – API does not support the requested media type.

Returns

List of Story objects

Return type

List[Story]

get_stories_keywords(keywords: List[str], media: str = None, start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for most recent press releases assigned to specific keywords.

Returns a list of pypresseportal.Story objects. More information: https://api.presseportal.de/doc/article/keyword/ident

Parameters

keywords (List[str]) – A list of one ore more keywords from https://api.presseportal.de/doc/value/keyword
media (str, optional) – Only request stories containing this specific media type (image, document, audio or video). Defaults to None.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
MediaError – API does not support the requested media type.
KeywordError – API does not support the requested keyword(s).

Returns

List of Story objects

Return type

List[Story]

get_stories_specific_company(id: str, media: str = None, start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for press releases of a specific company.

Returns a list of pypresseportal.Story objects. More information: https://api.presseportal.de/en/doc/article/company/id

Parameters

id (str) – id of company (read Entity.id of a get_entity_search_results() search for this id).
media (str, optional) – Only request stories containing this specific media type (image, document, audio or video). Defaults to None.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
MediaError – API does not support the requested media type.

Returns

List of Story objects

Return type

List[Story]

get_stories_topic(topic: str, media: str = None, start: int = 0, limit: int = 50, teaser: bool = False) → List[pypresseportal.pypresseportal.Story]¶

Queries API for most recent press releases assigned to a specific topic.

Returns a list of pypresseportal.Story objects. More information: https://api.presseportal.de/doc/article/topic/ident

Parameters

topic (str) – One specific topic from https://api.presseportal.de/doc/value/topic
media (str, optional) – Only request stories containing this specific media type (image, document, audio or video). Defaults to None.
start (int, optional) – Start/offset of the result article list. Defaults to 0.
limit (int, optional) – Limit number of articles in response (API maximum is 50). Defaults to 50.
teaser (bool, optional) – Returns stories with teaser instead of body (fulltext) if set to True. Defaults to False.

Raises

ApiConnectionFail – Could not connect to API.
ApiError – API returned an error.
MediaError – API does not support the requested media type.
TopicError – API does not support the requested topic.

Returns

List of Story objects

Return type

List[Story]

The `Story` class¶

class pypresseportal.Story(data: dict)¶

Represents a story retrieved through the API.

See original API documentation for details (https://api.presseportal.de/en/doc/format/story).

A Story object can contain different attributes, depending on the API query method:

data - The raw json data returned by the API.

id - The story’s unique id as generated by the API.

url - URL of the story on the presseportal.de website.

title - Headline of the story.

body - Full text body.

optional: teaser - Teaser text. Only included if teaser=True is passed to the API query method. If a teaser is requested, it will replace the body attribute.

published - Publication date (as datetime object).

language - Language of the story (usually ‘de’ or ‘en’).

ressort - Editorial department.

company_id/office_id - Unique id of the company or office publishing the story.

company_url/office_url - URL of the company or office publishing the story.

company_name/office_name - Name of the company or office publishing the story.

keywords - List of keywords assigned to the story.

optional: media - Information on media attachments, if present.

highlight - Promoted story flag (on/off).

short - Shortened URL.

The `Entity` class¶

class pypresseportal.Entity(data: dict)¶

Represents a company or a public service office search result.

An Entity object can have the following attributes: id, url, name, and type (company or office). See original API documentation for details (https://api.presseportal.de/doc/format/result).

The `Company` class¶

class pypresseportal.Company(data: dict)¶

Represents information about a company.

A Company object can have the following attributes: id, url, name, isin (optional), wkn (optional), shortname, rss, logo, web, and homepage. See original API documentation for details (https://api.presseportal.de/en/doc/format/company).

The `Office` class¶

class pypresseportal.Office(data: dict)¶

Represents information about a public service office.

An Office object can have the following attributes: id, url, name, shortname, rss, logo, web, and homepage. See original API documentation for details (https://api.presseportal.de/doc/format/office).

The pypresseportal_errors module¶

Error handling for PyPresseportal.

exception pypresseportal.pypresseportal_errors.ApiConnectionFail(error_msg: Union[requests.exceptions.ConnectionError, requests.exceptions.TooManyRedirects, requests.exceptions.Timeout])¶

Raised if requests raises an error.

Parameters: error_msg (Union[ requests.exceptions.ConnectionError, requests.exceptions.TooManyRedirects, requests.exceptions.Timeout, ]) – Error raised by requests package.

exception pypresseportal.pypresseportal_errors.ApiDataError(msg: str = None)¶

Raised if the API returned invalid data.

Parameters: msg (str, optional) – Custom error message. Defaults to None.

exception pypresseportal.pypresseportal_errors.ApiError(error_code: str, error_msg: str)¶

Raised if API returns an error.

Parameters

error_code (str) – Error code returned by API.
error_msg (str) – Error message returned by API.

exception pypresseportal.pypresseportal_errors.ApiKeyError(api_key: str)¶

Raised if no API key is provided.

Parameters: api – key (str): Invalid API key.

exception pypresseportal.pypresseportal_errors.KeywordError(keyword: str, allowed: tuple)¶

Raised if keyword is not supported. List of keywords: https://api.presseportal.de/en/doc/value/keyword.

Parameters

keyword (str) – Unsupported keyword.
allowed (list) – List of keyword allowed by API.

exception pypresseportal.pypresseportal_errors.MediaError(media: Optional[str], allowed: tuple)¶

Raised if media type is not supported. List of media types: https://api.presseportal.de/en/doc/value/media.

Parameters

media (str) – Unsupported media type.
allowed (list) – List of media types allowed by API.

exception pypresseportal.pypresseportal_errors.NewsTypeError(news_type: str, allowed: tuple)¶

Raised if investor relations news type is not supported. List of news types: https://api.presseportal.de/en/doc/value/ir_type.

Parameters

news_type (str) – Unsupported investor relations news type.
allowed (list) – List of investor relations news type allowed by API.

exception pypresseportal.pypresseportal_errors.RegionError(region: str, allowed: tuple)¶

Raised if region is not supported. List of regions: https://api.presseportal.de/en/doc/value/region.

Parameters

region (str) – Unsupported region.
allowed (list) – List of regions allowed by API.

exception pypresseportal.pypresseportal_errors.SearchEntityError(search_term: str)¶

Raised if entity for search is not supported.

Parameters: entity (str) – Unsupported entity.

exception pypresseportal.pypresseportal_errors.SearchTermError(search_term: str)¶

Raised if search term is not supported.

Parameters: search_term (str) – Unsupported search term.

exception pypresseportal.pypresseportal_errors.TopicError(topic: str, allowed: tuple)¶

Raised if topic is not supported. List of topics: https://api.presseportal.de/en/doc/value/topic.

Parameters

topic (str) – Unsupported topic.
allowed (list) – List of topics allowed by API.

Modules Documentation¶

The pypresseportal module¶

The PresseportalApi class¶

The Story class¶

The Entity class¶

The Company class¶

The Office class¶

The pypresseportal_errors module¶

The `PresseportalApi` class¶

The `Story` class¶

The `Entity` class¶

The `Company` class¶

The `Office` class¶