STT Info APIsttinfo.fi ↗

"""
STT Info Pörssitiedotteet API Client

Access Finnish stock exchange announcements from STT Info.
Supports paginated listing and keyword search across ~10,000 announcements.

Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, Any


class ParseClient:
    """Client for STT Info Pörssitiedotteet API."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.

        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "460621d2-545f-45ca-ac8a-08a0261c0805"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")

    def _call(self, endpoint: str, method: str = "POST", **params) -> dict[str, Any]:
        """
        Make a request to the Parse API.

        Args:
            endpoint: The API endpoint name
            method: HTTP method (GET or POST)
            **params: Query parameters or request body

        Returns:
            Response JSON as a dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}

        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params, timeout=30)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params, timeout=30)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def get_porssitiedotteet(
        self,
        page: int = 0,
        size: int = 20,
        language: str = "fi"
    ) -> dict[str, Any]:
        """
        Get paginated stock exchange announcements (Pörssitiedotteet) from STT Info.

        Returns headlines, publishers, dates, and categories.
        Total ~9961 announcements across ~499 pages (at size=20).

        Args:
            page: Zero-based page number for pagination. Default: 0
            size: Number of announcements per page (1-100). Default: 20
            language: Language for announcement titles (fi, en, sv, no, da). Default: fi

        Returns:
            Dictionary containing announcements, total_count, page info, and total_pages
        """
        return self._call(
            "get_porssitiedotteet",
            method="GET",
            page=page,
            size=size,
            language=language
        )

    def search_announcements(
        self,
        query: str,
        page: int = 0,
        size: int = 20,
        language: str = "fi"
    ) -> dict[str, Any]:
        """
        Search stock exchange announcements by keyword.

        Returns matching announcements with headlines, publishers, dates, and categories.

        Args:
            query: Search keyword to filter announcements (e.g. company name or topic)
            page: Zero-based page number for pagination. Default: 0
            size: Number of announcements per page (1-100). Default: 20
            language: Language for announcement titles (fi, en, sv, no, da). Default: fi

        Returns:
            Dictionary containing matching announcements and pagination info
        """
        return self._call(
            "search_announcements",
            method="GET",
            query=query,
            page=page,
            size=size,
            language=language
        )


if __name__ == "__main__":
    # Initialize the client
    client = ParseClient()

    print("=" * 80)
    print("STT Info Pörssitiedotteet API - Practical Usage Example")
    print("=" * 80)

    # Example 1: Get the most recent announcements
    print("\n1. Fetching the 5 most recent stock exchange announcements...")
    recent_result = client.get_porssitiedotteet(page=0, size=5, language="en")

    print(f"   Total announcements in database: {recent_result['total_count']}")
    print(f"   Showing page {recent_result['page'] + 1} of {recent_result['total_pages']}")
    print(f"   Items on this page: {len(recent_result['announcements'])}\n")

    for idx, announcement in enumerate(recent_result["announcements"], 1):
        print(f"   [{idx}] {announcement['title'][:60]}...")
        print(f"       Publisher: {announcement['publisher']}")
        print(f"       Date: {announcement['publication_date']}")
        print()

    # Example 2: Search for announcements about a specific topic
    search_query = "technology"
    print(f"\n2. Searching for announcements containing '{search_query}'...")
    search_result = client.search_announcements(query=search_query, size=3, language="en")

    if search_result["announcements"]:
        print(f"   Found {search_result['total_count']} announcements matching '{search_query}'")
        print(f"   Showing top 3 results:\n")

        for idx, announcement in enumerate(search_result["announcements"], 1):
            print(f"   [{idx}] {announcement['title'][:60]}...")
            print(f"       Publisher: {announcement['publisher']}")
            print(f"       Category: {announcement['category'].split('__')[-1]}")
            print(f"       ID: {announcement['id']}")
            print()
    else:
        print(f"   No announcements found matching '{search_query}'")

    # Example 3: Browse through multiple pages of results
    print("\n3. Browsing through multiple pages of announcements...")
    print("   Collecting announcements from pages 0-2 (3 items per page)...\n")

    all_announcements = []
    for page_num in range(3):
        page_result = client.get_porssitiedotteet(page=page_num, size=3, language="fi")
        all_announcements.extend(page_result["announcements"])

    print(f"   Collected {len(all_announcements)} announcements across 3 pages:")
    for announcement in all_announcements:
        publisher = announcement["publisher"]
        date = announcement["publication_date"].split("T")[0]  # Extract date part
        print(f"   - {date} | {publisher:30} | {announcement['title'][:40]}...")

    # Example 4: Search for a company and analyze results
    company_query = "Gofore"
    print(f"\n4. Searching for all announcements from '{company_query}'...")
    company_search = client.search_announcements(query=company_query, size=10, language="fi")

    if company_search["announcements"]:
        print(f"   Found {company_search['total_count']} announcements mentioning '{company_query}'")
        print(f"   Latest {len(company_search['announcements'])} announcements:\n")

        for announcement in company_search["announcements"]:
            date = announcement["publication_date"].split("T")[0]
            title = announcement["title"]
            print(f"   {date} - {title}")
    else:
        print(f"   No announcements found for '{company_query}'")

    print("\n" + "=" * 80)
    print("Example completed successfully!")
    print("=" * 80)