marketstack-python-client 1.0.0__py3-none-any.whl

marketstack/__init__.py

@@ -0,0 +1 @@
+from .client.marketstack import Marketstack

marketstack/client/http.py

@@ -0,0 +1,36 @@
+import httpx
+
+
+class HTTPClient:
+    def __init__(self, base_url: str, params: dict = None):
+        self.base_url = base_url
+        self.params = params or {}
+
+    def get(self, endpoint: str, params: dict = None):
+        merged_params = {**self.params}
+        if params:
+            cleaned_params = {k: v for k, v in params.items() if v is not None}
+            merged_params.update(cleaned_params)
+        with httpx.Client(base_url=self.base_url, timeout=30.0) as client:
+            response = client.get(endpoint, params=merged_params)
+            response.raise_for_status()
+            data = response.json()
+            if isinstance(data, dict):
+                if "error" in data:
+                    err = data["error"]
+                    err_msg = err.get("message", "Unknown error") if isinstance(err, dict) else str(err)
+                    err_code = err.get("code", "unknown") if isinstance(err, dict) else "unknown"
+                    raise httpx.HTTPStatusError(
+                        message=f"API Error ({err_code}): {err_msg}",
+                        request=response.request,
+                        response=response,
+                    )
+                if data.get("message") == "error":
+                    err_msg = data.get("details", "Unknown error")
+                    err_code = data.get("code", "unknown")
+                    raise httpx.HTTPStatusError(
+                        message=f"API Error ({err_code}): {err_msg}",
+                        request=response.request,
+                        response=response,
+                    )
+            return data

marketstack/client/marketstack.py

@@ -0,0 +1,148 @@
+from marketstack.client.http import HTTPClient
+from marketstack.namespaces.bond import Bond
+from marketstack.namespaces.bondlist import BondList
+from marketstack.namespaces.cikcode import CIKCode
+from marketstack.namespaces.commodities import Commodities
+from marketstack.namespaces.commoditieshistory import CommoditiesHistory
+from marketstack.namespaces.company_facts import CompanyFacts
+from marketstack.namespaces.companyname import CompanyName
+from marketstack.namespaces.companyratings import CompanyRatings
+from marketstack.namespaces.concept import Concept
+from marketstack.namespaces.currencies import Currencies
+from marketstack.namespaces.dividends import Dividends
+from marketstack.namespaces.eod import EOD
+from marketstack.namespaces.etfholdings import ETFHoldings
+from marketstack.namespaces.etflist import ETFList
+from marketstack.namespaces.exchanges import Exchanges
+from marketstack.namespaces.frames import Frames
+from marketstack.namespaces.indexinfo import IndexInfo
+from marketstack.namespaces.indexlist import IndexList
+from marketstack.namespaces.intraday import Intraday
+from marketstack.namespaces.splits import Splits
+from marketstack.namespaces.stockprice import StockPrice
+from marketstack.namespaces.submissions import Submissions
+from marketstack.namespaces.tickerinfo import TickerInfo
+from marketstack.namespaces.tickers import Tickers
+from marketstack.namespaces.tickerslist import TickersList
+from marketstack.namespaces.timezones import Timezones
+
+
+class Marketstack:
+    """
+    The marketstack API was built to deliver worldwide stock market data
+    (real-time, intraday and historical), together with information on stock
+    exchanges, tickers, indices, ETFs, bonds, commodities and company
+    fundamentals, in a simple, lightweight JSON format. Requests to the REST API
+    are made using a straightforward HTTP GET URL structure. This documentation
+    covers the v2 API surface.
+    """
+
+    def __init__(self, api_key: str):
+        self.http_client = HTTPClient(
+            base_url="https://api.marketstack.com",
+            params={"access_key": api_key},
+        )
+
+    @property
+    def bond(self) -> Bond:
+        return Bond(http_client=self.http_client)
+
+    @property
+    def bondlist(self) -> BondList:
+        return BondList(http_client=self.http_client)
+
+    @property
+    def cikcode(self) -> CIKCode:
+        return CIKCode(http_client=self.http_client)
+
+    @property
+    def commodities(self) -> Commodities:
+        return Commodities(http_client=self.http_client)
+
+    @property
+    def commoditieshistory(self) -> CommoditiesHistory:
+        return CommoditiesHistory(http_client=self.http_client)
+
+    @property
+    def company_facts(self) -> CompanyFacts:
+        return CompanyFacts(http_client=self.http_client)
+
+    @property
+    def companyname(self) -> CompanyName:
+        return CompanyName(http_client=self.http_client)
+
+    @property
+    def companyratings(self) -> CompanyRatings:
+        return CompanyRatings(http_client=self.http_client)
+
+    @property
+    def concept(self) -> Concept:
+        return Concept(http_client=self.http_client)
+
+    @property
+    def currencies(self) -> Currencies:
+        return Currencies(http_client=self.http_client)
+
+    @property
+    def dividends(self) -> Dividends:
+        return Dividends(http_client=self.http_client)
+
+    @property
+    def eod(self) -> EOD:
+        return EOD(http_client=self.http_client)
+
+    @property
+    def etfholdings(self) -> ETFHoldings:
+        return ETFHoldings(http_client=self.http_client)
+
+    @property
+    def etflist(self) -> ETFList:
+        return ETFList(http_client=self.http_client)
+
+    @property
+    def exchanges(self) -> Exchanges:
+        return Exchanges(http_client=self.http_client)
+
+    @property
+    def frames(self) -> Frames:
+        return Frames(http_client=self.http_client)
+
+    @property
+    def indexinfo(self) -> IndexInfo:
+        return IndexInfo(http_client=self.http_client)
+
+    @property
+    def indexlist(self) -> IndexList:
+        return IndexList(http_client=self.http_client)
+
+    @property
+    def intraday(self) -> Intraday:
+        return Intraday(http_client=self.http_client)
+
+    @property
+    def splits(self) -> Splits:
+        return Splits(http_client=self.http_client)
+
+    @property
+    def stockprice(self) -> StockPrice:
+        return StockPrice(http_client=self.http_client)
+
+    @property
+    def submissions(self) -> Submissions:
+        return Submissions(http_client=self.http_client)
+
+    @property
+    def tickerinfo(self) -> TickerInfo:
+        return TickerInfo(http_client=self.http_client)
+
+    @property
+    def tickers(self) -> Tickers:
+        return Tickers(http_client=self.http_client)
+
+    @property
+    def tickerslist(self) -> TickersList:
+        return TickersList(http_client=self.http_client)
+
+    @property
+    def timezones(self) -> Timezones:
+        return Timezones(http_client=self.http_client)

marketstack/models/bond.py

@@ -0,0 +1,47 @@
+from pydantic import BaseModel, Field
+from typing import Union
+from types import NoneType
+from .pagination import Pagniation, PaginationRequest
+from typing import TypedDict
+
+
+class BondRequest(TypedDict, total=False):
+    country: Union[NoneType, str] = None
+    """Filter bonds by country."""
+
+class BondListRequest(PaginationRequest, total=False):
+    country: Union[NoneType, str] = None
+    """Filter bond list by country."""
+
+class BondInfoItem(BaseModel):
+    region: str
+    """Region where the bond is supported."""
+    country: str
+    """Country where the bond is supported."""
+    type: str
+    """Bond tenor/type (for example 10Y)."""
+    yield_: str = Field(..., alias="yield")
+    """Current bond yield."""
+    price_change_day: str
+    """Price change day-over-day."""
+    percentage_week: str
+    """Weekly change percentage."""
+    percentage_month: str
+    """Monthly change percentage."""
+    percentage_year: str
+    """Yearly change percentage."""
+    date: str
+    """Quote date."""
+    model_config = {"populate_by_name": True}
+
+class BondInfoResponse(BaseModel):
+    pagination: Pagniation
+    data: list["BondInfoItem"]
+
+class BondListItem(BaseModel):
+    country: str
+    """Country supported for bonds."""
+
+class BondListResponse(BaseModel):
+    pagination: Pagniation
+    data: list["BondListItem"]

marketstack/models/cik_code.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel
+from typing import Union
+from types import NoneType
+from .pagination import Pagniation, PaginationRequest
+from typing import TypedDict
+
+
+class CIKCodeRequest(PaginationRequest, total=False):
+    company_name: Union[NoneType, str] = None
+    """Search by company name."""
+
+class CIKItem(BaseModel):
+    cik_code: str
+    """Company CIK code."""
+    company_name: str
+    """Company name."""
+    ein: str
+    """Employer Identification Number."""
+    sic: str
+    """Standard Industrial Classification."""
+    sic_description: str
+    """SIC description."""
+
+class CIKSearchResponse(BaseModel):
+    pagination: Pagniation
+    data: list["CIKItem"]

marketstack/models/commodity.py

@@ -0,0 +1,83 @@
+from pydantic import BaseModel
+from typing import Union
+from types import NoneType
+from .pagination import Pagniation, PaginationRequest
+from typing import TypedDict
+
+
+class CommoditiesRequest(TypedDict, total=False):
+    commodity_name: Union[NoneType, str] = None
+    """Filter by commodity name."""
+
+
+class CommoditiesHistoryRequest(TypedDict, total=False):
+    commodity_name: Union[NoneType, str] = None
+    """Filter by commodity name."""
+    date_from: Union[NoneType, str] = None
+    """Start date."""
+    date_to: Union[NoneType, str] = None
+    """End date."""
+    frequency: Union[NoneType, str] = None
+    """Frequency (e.g. 1day)."""
+
+
+class CommodityItem(BaseModel):
+    commodity_name: str
+    """Name of the commodity."""
+    commodity_unit: str
+    """Unit of the commodity."""
+    commodity_price: str
+    """Current price of the commodity."""
+    price_change_day: str
+    """Absolute day change."""
+    percentage_day: str
+    """Day change in percent."""
+    percentage_week: str
+    """Week change in percent."""
+    percentage_month: str
+    """Month change in percent."""
+    percentage_year: str
+    """Year change in percent."""
+    quarter1_25: str
+    """Value for the first quarter of 2025."""
+    quarter2_25: str
+    """Value for the second quarter of 2025."""
+    quarter3_25: str
+    """Value for the third quarter of 2025."""
+    quarter4_25: str
+    """Value for the fourth quarter of 2025."""
+    datetime: str
+    """Timestamp of the commodity price in ISO8601 format."""
+
+
+class CommodityResponse(BaseModel):
+    data: list[CommodityItem]
+
+
+class CommodityHistoricalBasics(BaseModel):
+    frequency: str
+    """Frequency of the historical data (e.g., 1day, 1month)."""
+
+
+class CommodityPriceItem(BaseModel):
+    commodity_price: str
+    """Price of the commodity for the date."""
+    date: str
+    """Date for the price (YYYY-MM-DD or YYYY-MM for monthly)."""
+
+
+class CommodityHistoricalData(BaseModel):
+    commodity_name: str
+    """Name of the commodity."""
+    commodity_unit: str
+    """Unit of the commodity."""
+    commodity_prices: list[CommodityPriceItem]
+
+
+class CommodityHistoricalResult(BaseModel):
+    basics: CommodityHistoricalBasics
+    data: list[CommodityHistoricalData]
+
+
+class CommodityHistoricalResponse(BaseModel):
+    result: CommodityHistoricalResult

marketstack/models/company.py

@@ -0,0 +1,278 @@
+from pydantic import BaseModel, Field
+from typing import Union
+from types import NoneType
+from .pagination import Pagniation, PaginationRequest
+from typing import TypedDict
+
+
+class CompanyFactsRequest(PaginationRequest, total=False):
+    cik_code: Union[NoneType, str] = None
+    """Filter by CIK code."""
+
+class CompanyNameRequest(PaginationRequest, total=False):
+    cik_code: Union[NoneType, str] = None
+    """Filter by CIK code."""
+
+class CompanyRatingsRequest(TypedDict, total=False):
+    ticker: Union[NoneType, str] = None
+    """Filter by stock ticker symbol."""
+    date_from: Union[NoneType, str] = None
+    """Start date."""
+    date_to: Union[NoneType, str] = None
+    """End date."""
+    rated: Union[NoneType, str] = None
+    """Filter by rating."""
+
+class SubmissionsRequest(TypedDict, total=False):
+    cik_code: Union[NoneType, str] = None
+    """Filter by CIK code."""
+    accession_number: Union[NoneType, str] = None
+    """Filter by accession number."""
+    cik_code_name: Union[NoneType, str] = None
+    """Filter by CIK name."""
+    filing_from: Union[NoneType, str] = None
+    """Start date."""
+    filing_to: Union[NoneType, str] = None
+    """End date."""
+    report_from: Union[NoneType, str] = None
+    """Report start date."""
+    report_to: Union[NoneType, str] = None
+    """Report end date."""
+
+class CompanyFactUnitItem(BaseModel):
+    fp: Union[NoneType, str] = None
+    """Fiscal period (e.g. Q3, FY)."""
+    fy: Union[NoneType, int] = None
+    """Fiscal year."""
+    start: Union[NoneType, str] = None
+    """Period start date. Present on duration concepts (e.g. revenue, expenses); absent on point-in-time concepts."""
+    end: Union[NoneType, str] = None
+    """Period end date."""
+    val: float
+    """Reported value."""
+    accn: str
+    """Accession number of the source filing."""
+    form: str
+    """Filing form type (e.g. 10-K, 10-Q)."""
+    filed: str
+    """Filing date."""
+    frame: Union[NoneType, str] = None
+    """CY frame identifier (present when comparable)."""
+
+class CompanyFactConcept(BaseModel):
+    """A single XBRL concept."""
+    label: str
+    """Human-readable concept label."""
+    description: str
+    """Concept definition."""
+    units: dict[str, list[CompanyFactUnitItem]]
+    """Fact values keyed by unit of measure (e.g. USD, shares)."""
+
+class CompanyFactsData(BaseModel):
+    cik: int
+    """SEC Central Index Key."""
+    company_name: str
+    """Company name."""
+    facts: dict[str, dict[str, CompanyFactConcept]]
+    """XBRL concepts keyed by taxonomy (e.g. dei, us-gaap), then by concept tag. Keys are dynamic; the value shape below is consistent."""
+
+class CompanyFactsByCIKResponse(BaseModel):
+    data: CompanyFactsData
+
+class CompanyAddress(BaseModel):
+    street1: str
+    street2: str
+    city: str
+    state_or_country: str
+    zip_code: str
+
+class CompanyAddresses(BaseModel):
+    """Mailing and business addresses."""
+    mailing: Union[NoneType, CompanyAddress] = None
+    business: Union[NoneType, CompanyAddress] = None
+
+class CompanyNameData(BaseModel):
+    cik_code: str
+    """Company CIK code."""
+    company_name: str
+    """Company name."""
+    ein: str
+    """Employer Identification Number."""
+    sic: str
+    """Standard Industrial Classification code."""
+    sic_description: str
+    """SIC description."""
+    phone: str
+    """Company registered phone."""
+    incorporation_state: str
+    """Abbreviation of the incorporation state."""
+    addresses: CompanyAddresses
+    """Mailing and business addresses."""
+
+class CompanyNameByCIKResponse(BaseModel):
+    data: CompanyNameData
+
+class CompanyRatingsStatus(BaseModel):
+    code: int
+    """HTTP status code."""
+    message: str
+    """Status message."""
+    details: Union[NoneType, str] = None
+    """Additional details."""
+
+class CompanyRatingsBasics(BaseModel):
+    company_name: str
+    """Name of the company."""
+    ticker: str
+    """Ticker symbol."""
+
+class AnalystConsensus(BaseModel):
+    consensus_conclusion: str
+    """Overall consensus (e.g. Buy, Hold, Sell)."""
+    stock_price: str
+    """Current stock price."""
+    analyst_average: str
+    """Average analyst price target."""
+    analyst_highest: str
+    """Highest analyst price target."""
+    analyst_lowest: str
+    """Lowest analyst price target."""
+    analysts_number: str
+    """Number of contributing analysts."""
+    buy: str
+    """Count of buy ratings."""
+    hold: str
+    """Count of hold ratings."""
+    sell: str
+    """Count of sell ratings."""
+    consensus_date: str
+    """Date of the consensus."""
+
+class AnalystRatingDetail(BaseModel):
+    date_rating: str
+    """Date the rating was issued."""
+    target_date: str
+    """Target date for the price target."""
+    price_target: str
+    """Analyst price target."""
+    rated: str
+    """Rating (buy, sell, hold)."""
+    conclusion: str
+    """Rating conclusion."""
+
+class AnalystItem(BaseModel):
+    analyst_name: str
+    """Analyst name."""
+    analyst_firm: str
+    """Analyst firm."""
+    analyst_role: str
+    """Analyst role/title."""
+    rating: AnalystRatingDetail
+
+class CompanyRatingsOutput(BaseModel):
+    """Analyst consensus and individual analyst ratings."""
+    analyst_consensus: AnalystConsensus
+    analysts: list[AnalystItem]
+    """Individual analyst ratings."""
+
+class CompanyRatingsResult(BaseModel):
+    basics: CompanyRatingsBasics
+    output: CompanyRatingsOutput
+    """Analyst consensus and individual analyst ratings."""
+
+class CompanyRatingsResponse(BaseModel):
+    status: "CompanyRatingsStatus"
+    result: "CompanyRatingsResult"
+
+class FormerName(BaseModel):
+    name: str
+    from_: str = Field(..., alias="from")
+    to: str
+    model_config = {"populate_by_name": True}
+
+class RecentFilings(BaseModel):
+    """Most recent filings as index-aligned parallel arrays."""
+    accession_number: list[str]
+    filing_date: list[str]
+    report_date: list[str]
+    acceptance_date_time: list[str]
+    act: list[str]
+    form: list[str]
+    file_number: list[str]
+    film_number: list[str]
+    core_type: list[str]
+    size: list[int]
+    primary_document: list[str]
+    primary_doc_description: list[str]
+
+class OlderFilingFile(BaseModel):
+    name: str
+    filing_count: int
+    filing_from: str
+    filing_to: str
+
+class SubmissionsFilings(BaseModel):
+    """Recent filings and paginated file references."""
+    recent: RecentFilings
+    """Most recent filings as index-aligned parallel arrays."""
+    files: list[OlderFilingFile]
+    """References to older, paginated filing files."""
+
+class SubmissionsData(BaseModel):
+    cik_code: str
+    """SEC Central Index Key (zero-padded)."""
+    company_name: str
+    """Company name."""
+    entity_type: str
+    """Entity type (e.g. operating)."""
+    ein: str
+    """Employer Identification Number."""
+    sic: str
+    """Standard Industrial Classification code."""
+    sic_description: str
+    """SIC description."""
+    owner_org: str
+    """SEC owner organization classification."""
+    insider_transaction_for_owner_exists: int
+    """Whether insider transactions exist for the owner (0 or 1)."""
+    insider_transaction_for_issuer_exists: int
+    """Whether insider transactions exist for the issuer (0 or 1)."""
+    tickers: list[str]
+    exchanges: list[str]
+    description: str
+    """Company description."""
+    website: str
+    """Company website."""
+    investor_website: str
+    """Investor relations website."""
+    category_filer: str
+    """Filer category (e.g. Large accelerated filer)."""
+    fiscal_year_end: str
+    """Fiscal year end (MMDD)."""
+    incorporation_state_or_country: str
+    """State or country of incorporation."""
+    incorporation_state_or_country_desc: str
+    """State or country of incorporation, described."""
+    phone: str
+    """Company phone number."""
+    addresses: CompanyAddresses
+    """Mailing and business addresses."""
+    former_names: list[FormerName]
+    """Previous company names with active date ranges."""
+    filings: SubmissionsFilings
+    """Recent filings and paginated file references."""
+
+class SubmissionsByCIKResponse(BaseModel):
+    data: SubmissionsData
+
+
+# Rebuild models to resolve forward references
+CompanyFactsByCIKResponse.model_rebuild()
+CompanyNameByCIKResponse.model_rebuild()
+CompanyRatingsResponse.model_rebuild()
+CompanyRatingsResult.model_rebuild()
+CompanyRatingsOutput.model_rebuild()
+AnalystItem.model_rebuild()
+SubmissionsByCIKResponse.model_rebuild()
+SubmissionsData.model_rebuild()
+SubmissionsFilings.model_rebuild()

marketstack/models/concept.py

@@ -0,0 +1,65 @@
+from pydantic import BaseModel, Field
+from typing import Union
+from types import NoneType
+from .company import CompanyFactConcept
+from .pagination import Pagniation, PaginationRequest
+from typing import TypedDict
+
+
+class ConceptRequest(PaginationRequest, total=False):
+    cik_code: Union[NoneType, str] = None
+    """Filter by CIK code."""
+
+
+class FramesRequest(PaginationRequest, total=False):
+    frame: Union[NoneType, str] = None
+    """Specify CY frame identifier."""
+
+
+class AccountsPayableData(BaseModel):
+    cik: int
+    """SEC Central Index Key."""
+    company_name: str
+    """Company name."""
+    us_gaap: dict[str, CompanyFactConcept] = Field(..., alias="us-gaap")
+    """US GAAP concepts keyed by tag (e.g. AccountsPayableCurrent)."""
+
+    model_config = {"populate_by_name": True}
+
+
+class AccountsPayableResponse(BaseModel):
+    data: AccountsPayableData
+
+
+class FrameDataItem(BaseModel):
+    accn: str
+    """Accession number."""
+    cik: int
+    """SEC Central Index Key."""
+    entityName: str
+    """Entity name."""
+    end: str
+    """End date (YYYY-MM-DD)."""
+    val: float
+    """Value."""
+
+
+class FrameData(BaseModel):
+    taxonomy: str
+    """Taxonomy (e.g., us-gaap)."""
+    tag: str
+    """Tag name (e.g., AccountsPayableCurrent)."""
+    ccp: str
+    """Calendar period code (e.g., CY2023Q1I)."""
+    uom: str
+    """Unit of measure (e.g., USD)."""
+    label: str
+    """Concept label."""
+    description: str
+    """Concept description."""
+    frame_data: list[FrameDataItem]
+
+
+class FrameResponse(BaseModel):
+    pagination: Pagniation
+    data: FrameData