fmp

Financial Modeling Prep endpoint and type scaffolding for Kit, focused on macroeconomic and calendar data

Files

FileDescription
.editorconfigEditor formatting configuration
.gitignoreGit ignore rules for build artifacts and local package state
.tool-versionsasdf tool versions
LICENSEMIT license file
README.mdThis file
examples/analyst-estimates.kitExample: analyst estimates
examples/analyst-grade-changes.kitExample: analyst grade changes
examples/analyst-grades-summary.kitExample: analyst grades summary
examples/analyst-research.kitExample: combined analyst workflow
examples/company-profile.kitExample: company profile
examples/earnings-call-dates.kitExample: earnings call dates
examples/earnings-call-transcript.kitExample: earnings call transcript
examples/earnings-reports.kitExample: earnings reports
examples/financial-score.kitExample: financial score
examples/historical-earnings-calendar.kitExample: historical earnings calendar
examples/historical-ratings.kitExample: historical ratings
examples/key-executives.kitExample: key executives
examples/macro-data.kitExample: macroeconomic and calendar data
examples/price-target-summary.kitExample: price target summary
examples/rating-snapshot.kitExample: rating snapshot
examples/revenue-geographic-segmentation.kitExample: revenue geographic segmentation
examples/revenue-product-segmentation.kitExample: revenue product segmentation
examples/sec-filings.kitExample: SEC filings
kit.tomlPackage manifest with metadata, capabilities, dependencies, and tasks
src/analyst_types.kitAnalyst type re-export module
src/errors.kitFMP error types and constructors
src/main.kitPublic Kit.FMP package surface
src/parsers.kitCore JSON parsers for FMP responses
src/parsers_earnings.kitHistorical earnings parser helpers
src/parsers_score.kitFinancial score parser helpers
src/parsers_sec.kitSEC filing parser helpers
src/parsers_segmentation.kitRevenue segmentation parser helpers
src/parsers_transcript.kitEarnings call parser helpers
src/segmentation_types.kitSegmentation type re-export module
src/types.kitCore FMP record and enum types
src/types_analyst.kitAnalyst, rating, and transcript types
src/types_earnings.kitHistorical earnings calendar types
src/types_score.kitFinancial score types
src/types_sec.kitSEC filing types
src/types_segmentation.kitRevenue segmentation types
src/urls.kitStable FMP endpoint URL builders
tests/errors.test.kitTests for error helpers
tests/parsers.test.kitTests for core parsers
tests/parsers-analyst.test.kitTests for analyst parsers
tests/types.test.kitTests for core public types
tests/types-analyst.test.kitTests for analyst public types
tests/urls.test.kitTests for endpoint URL builders

Dependencies

  • kit-curl - HTTP transport for live FMP API calls

Live requests require network access and kit-curl requires FFI access.

Installation

kit add gitlab.com/kit-lang/packages/kit-fmp.git

Usage

import Env
import Kit.FMP as FMP

main = fn(env: Env) =>
  api-key = env.get "FMP_API_KEY" ?? "demo"
  range = FMP.date-range "2026-01-01" "2026-01-31"

  match FMP.get-economic-indicator api-key FMP.GDP 3
    | Ok observations ->
        println "GDP observations: ${Int.to-string (List.length observations)}"
    | Err e ->
        println "Error fetching GDP observations: ${show e}"

  match FMP.get-economic-calendar api-key range
    | Ok events ->
        println "Calendar events: ${Int.to-string (List.length events)}"
    | Err e ->
        println "Error fetching economic calendar: ${show e}"

main

Development

Running Examples

Set FMP_API_KEY for live examples:

export FMP_API_KEY=your-api-key

Run examples with the interpreter:

kit run examples/macro-data.kit --allow=net,ffi,env

Compile examples to a native binary:

kit build examples/macro-data.kit -o macro-data --allow=net,ffi,env
./macro-data

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

  1. Format and check source files in src/
  2. Run tests in tests/ with coverage

Running Parity

Run interpreter/compiler parity across examples:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/fmp/, making it available for import as Kit.FMP in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Financial Modeling Prep is a third-party service. API keys, data access, and usage terms are governed by Financial Modeling Prep.

Exported Functions & Types

HistoricalEarningsCalendarEvent

Historical and upcoming earnings calendar row from FMP's v3 symbol calendar endpoint.

Variants

HistoricalEarningsCalendarEvent {date, fiscal-date-ending, time, eps-actual, eps-estimate, revenue-actual, revenue-estimate}

FMPError

FMP transport and parsing errors.

Variants

InvalidAPIKey {message}
RateLimitExceeded {message}
NetworkError {message}
ParseError {message}
APIError {status, message}

error-kind

Return the stable symbolic error kind for an FMP error.

FMPError -> Symbol

error-message

Return the human-readable error message for an FMP error.

FMPError -> String

parse-error

Construct a parse error for malformed JSON or unexpected payloads.

String -> FMPError

network-error

Construct a network error from a lower-level transport message.

String -> FMPError

http-error

Map an HTTP status/body pair into the package error surface.

Int -> String -> FMPError

PriceTargetSummary

Re-export the normalized analyst price-target summary row.

Type

Variants

PriceTargetSummary

AnalystGradesSummary

Re-export the normalized analyst grades summary row.

Type

Variants

AnalystGradesSummary

AnalystGradeChange

Re-export the normalized analyst grade-change row.

Type

Variants

AnalystGradeChange

EstimatePeriod

Re-export the supported analyst-estimate period enum.

Type

Variants

EstimatePeriod

AnalystEstimate

Re-export the normalized analyst estimate row.

Type

Variants

AnalystEstimate

RatingSnapshot

Re-export the normalized ratings snapshot row.

Type

Variants

RatingSnapshot

HistoricalRating

Re-export the normalized historical ratings row.

Type

Variants

HistoricalRating

EarningsReport

Re-export the normalized earnings report row.

Type

Variants

EarningsReport

EarningsCallDate

Re-export the normalized earnings call transcript-date row.

Type

Variants

EarningsCallDate

EarningsCallTranscript

Re-export the normalized earnings call transcript row.

Type

Variants

EarningsCallTranscript

FinancialScore

Financial health score row from FMP's v4 score endpoint.

Variants

FinancialScore {symbol, altman-z-score, piotroski-score}

DateRange

Re-export the shared calendar date range type.

Type

Variants

InternalDateRange

EconomicIndicatorName

Re-export the supported FMP macro indicator enum.

Type

Variants

EconomicIndicatorName

EconomicObservation

Re-export the normalized economic observation row.

Type

Variants

EconomicObservation

EconomicCalendarEvent

Re-export the normalized economic calendar row.

Type

Variants

EconomicCalendarEvent

TreasuryRates

Re-export the normalized treasury-rate row.

Type

Variants

TreasuryRates

MarketRiskPremium

Re-export the normalized market risk premium row.

Type

Variants

MarketRiskPremium

EarningsCalendarEvent

Re-export the normalized earnings calendar row.

Type

Variants

EarningsCalendarEvent

CompanyProfile

Re-export the normalized company profile row.

Type

Variants

CompanyProfile

SharesFloat

Re-export the normalized shares float row.

Type

Variants

SharesFloat

KeyExecutive

Re-export the normalized key executive row.

Type

Variants

KeyExecutive

SECFiling

Re-export the normalized SEC filing row.

Type

Variants

SECFiling

HistoricalEarningsCalendarEvent

Re-export the normalized symbol-specific historical earnings calendar row.

Type

Variants

HistoricalEarningsCalendarEvent

FinancialScore

Re-export the normalized financial health score row.

Type

Variants

FinancialScore

RevenueSegmentationPeriod

Re-export the revenue segmentation period enum.

Type

Variants

RevenueSegmentationPeriod

RevenueSegmentValue

Re-export the normalized segment value row.

Type

Variants

RevenueSegmentValue

RevenueSegmentationRow

Re-export the normalized revenue segmentation row.

Type

Variants

RevenueSegmentationRow

PriceTargetSummary

Re-export the normalized analyst price-target summary row.

Type

Variants

PriceTargetSummary

AnalystGradesSummary

Re-export the normalized analyst grades summary row.

Type

Variants

AnalystGradesSummary

AnalystGradeChange

Re-export the normalized analyst grade-change row.

Type

Variants

AnalystGradeChange

EstimatePeriod

Re-export the supported analyst-estimate period enum.

Type

Variants

EstimatePeriod

AnalystEstimate

Re-export the normalized analyst estimate row.

Type

Variants

AnalystEstimate

RatingSnapshot

Re-export the normalized ratings snapshot row.

Type

Variants

RatingSnapshot

HistoricalRating

Re-export the normalized historical ratings row.

Type

Variants

HistoricalRating

EarningsReport

Re-export the normalized earnings report row.

Type

Variants

EarningsReport

EarningsCallDate

Re-export the normalized earnings call transcript-date row.

Type

Variants

EarningsCallDate

EarningsCallTranscript

Re-export the normalized earnings call transcript row.

Type

Variants

EarningsCallTranscript

FMPError

Re-export the package error surface.

Type

Variants

FMPError

GDP

Re-export the supported macro indicator constructors.

EconomicIndicatorName

CPI

EconomicIndicatorName

UnemploymentRate

EconomicIndicatorName

FederalFundsRate

EconomicIndicatorName

InflationRate

EconomicIndicatorName

RetailSales

EconomicIndicatorName

IndustrialProductionTotalIndex

EconomicIndicatorName

HousingStarts

EconomicIndicatorName

ConsumerSentiment

EconomicIndicatorName

NonFarmPayrolls

EconomicIndicatorName

date-range

Build a calendar date range for date-bounded endpoints.

String -> String -> DateRange

estimate-annual

Re-export the supported analyst estimate periods as value constants.

estimate-quarter

Re-export the supported quarterly analyst estimate period value.

segmentation-annual

Re-export the supported revenue segmentation periods as value constants.

segmentation-quarter

Re-export the supported quarterly revenue segmentation period value.

get-economic-indicator

Fetch an economic indicator time series from the stable FMP API.

String -> EconomicIndicatorName -> Int -> Result [EconomicObservation] FMPError

get-economic-calendar

Fetch the economic calendar for a date range from the stable FMP API.

String -> DateRange -> Result [EconomicCalendarEvent] FMPError

get-treasury-rates

Fetch treasury rates from the stable FMP API.

String -> DateRange -> Result [TreasuryRates] FMPError

get-market-risk-premium

Fetch market risk premium rows from the stable FMP API.

String -> Result [MarketRiskPremium] FMPError

get-company-profile

Fetch a company profile row from the FMP profile endpoint.

String -> String -> Result CompanyProfile FMPError

get-shares-float

Fetch shares float rows from FMP's stable shares-float endpoint.

String -> String -> Result [SharesFloat] FMPError

get-key-executives

Fetch key executives from FMP's stable key-executives endpoint.

String -> String -> Result [KeyExecutive] FMPError

get-sec-filings

Fetch SEC filings from FMP's v3 sec_filings endpoint.

String -> String -> Option String -> Int -> Result [SECFiling] FMPError

get-historical-earnings-calendar

Fetch historical and upcoming earnings calendar rows for a symbol from FMP's v3 endpoint.

String -> String -> Int -> Result [HistoricalEarningsCalendarEvent] FMPError

get-financial-score

Fetch financial health score rows from FMP's v4 score endpoint.

String -> String -> Result [FinancialScore] FMPError

get-revenue-product-segmentation

Fetch flat revenue-by-product segmentation rows from FMP's v4 endpoint.

String -> String -> RevenueSegmentationPeriod -> Result [RevenueSegmentationRow] FMPError

get-revenue-geographic-segmentation

Fetch flat revenue-by-geography segmentation rows from FMP's v4 endpoint.

String -> String -> RevenueSegmentationPeriod -> Result [RevenueSegmentationRow] FMPError

get-price-target-summary

Fetch analyst price-target summary rows from FMP's v4 endpoint.

String -> String -> Result [PriceTargetSummary] FMPError

get-analyst-grades-summary

Fetch analyst grades summary rows from FMP's stable grades-consensus endpoint.

String -> String -> Result [AnalystGradesSummary] FMPError

get-analyst-grade-changes

Fetch recent analyst grade changes from FMP's stable grades endpoint.

String -> String -> Int -> Result [AnalystGradeChange] FMPError

get-analyst-estimates

Fetch analyst financial estimates from FMP's stable analyst-estimates endpoint.

String -> String -> EstimatePeriod -> Int -> Result [AnalystEstimate] FMPError

get-rating-snapshot

Fetch ratings snapshot rows from FMP's stable ratings-snapshot endpoint.

String -> String -> Result [RatingSnapshot] FMPError

get-historical-ratings

Fetch historical ratings rows from FMP's stable ratings-historical endpoint.

String -> String -> Result [HistoricalRating] FMPError

get-earnings-reports

Fetch historical earnings report rows from FMP's stable earnings endpoint.

String -> String -> Int -> Result [EarningsReport] FMPError

get-earnings-call-dates

Fetch earnings call transcript metadata rows from FMP's v4 transcript-dates endpoint.

String -> String -> Result [EarningsCallDate] FMPError

get-earnings-call-transcript

Fetch full earnings call transcript rows from FMP's stable transcript endpoint.

String -> String -> Int -> Int -> Result [EarningsCallTranscript] FMPError

get-earnings-calendar

Fetch the earnings calendar for a date range from the stable FMP API.

String -> DateRange -> Result [EarningsCalendarEvent] FMPError

parse-revenue-segmentation-row

Decode a flat revenue segmentation row from FMP's v4 endpoints.

JSONValue -> RevenueSegmentationRow

parse-earnings-call-date

Decode an earnings call transcript metadata row from FMP's v4 transcript-dates endpoint.

JSONValue -> EarningsCallDate

parse-earnings-call-transcript

Decode a full earnings call transcript row from FMP's stable transcript endpoint.

JSONValue -> EarningsCallTranscript

RevenueSegmentationPeriod

Period selection for revenue segmentation endpoints.

Variants

SegmentationAnnual
SegmentationQuarter

RevenueSegmentValue

Single named segment and its revenue amount.

Variants

RevenueSegmentValue {segment, revenue}

RevenueSegmentationRow

Flat revenue segmentation row from FMP's v4 product/geographic endpoints.

Variants

RevenueSegmentationRow {symbol, date, calendar-year, period, segments}

parse-financial-score

Decode a financial health score row from FMP's v4 score endpoint.

JSONValue -> FinancialScore

base-url

Return the stable FMP base URL used by the Phase 1 endpoint builders.

String

requires-api-key?

FMP requires an API key for live requests.

Bool

indicator-name

Return the provider indicator slug expected by FMP.

EconomicIndicatorName -> String

economic-indicator-url

Build the stable FMP URL for an economic indicator time series request.

String -> EconomicIndicatorName -> Int -> String

economic-calendar-url

Build the stable FMP URL for an economic calendar request.

String -> DateRange -> String

treasury-rates-url

Build the stable FMP URL for a treasury rates request.

String -> DateRange -> String

market-risk-premium-url

Build the stable FMP URL for the market risk premium dataset.

String -> String

company-profile-url

Build the FMP profile URL for a company symbol.

String -> String -> String

shares-float-url

Build the stable FMP shares-float URL for a company symbol.

String -> String -> String

key-executives-url

Build the stable FMP key-executives URL for a company symbol.

String -> String -> String

sec-filings-url

Build the v3 FMP SEC filings URL for a company symbol, optional filing type, and limit.

String -> String -> Option String -> Int -> String

historical-earnings-calendar-url

Build the v3 FMP symbol-specific historical earnings calendar URL.

String -> String -> String

financial-score-url

Build the v4 FMP financial health score URL for a company symbol.

String -> String -> String

revenue-product-segmentation-url

Build the v4 FMP revenue-by-product segmentation URL for a company symbol and period.

String -> String -> RevenueSegmentationPeriod -> String

revenue-geographic-segmentation-url

Build the v4 FMP revenue-by-geography segmentation URL for a company symbol and period.

String -> String -> RevenueSegmentationPeriod -> String

price-target-summary-url

Build the v4 FMP price-target-summary URL for a company symbol.

String -> String -> String

analyst-grades-summary-url

Build the stable FMP grades-consensus URL for a company symbol.

String -> String -> String

analyst-grade-changes-url

Build the stable FMP grades URL for a company symbol and limit.

String -> String -> Int -> String

analyst-estimates-url

Build the stable FMP analyst-estimates URL for a company symbol, period, and limit.

String -> String -> EstimatePeriod -> Int -> String

rating-snapshot-url

Build the stable FMP ratings-snapshot URL for a company symbol.

String -> String -> String

historical-ratings-url

Build the stable FMP ratings-historical URL for a company symbol.

String -> String -> String

earnings-reports-url

Build the stable FMP earnings URL for a company symbol and limit.

String -> String -> Int -> String

earnings-call-dates-url

Build the v4 FMP earnings-call transcript-dates URL for a company symbol.

String -> String -> String

earnings-call-transcript-url

Build the stable FMP earnings-call transcript URL for a company symbol, year, and quarter.

String -> String -> Int -> Int -> String

earnings-calendar-url

Build the stable FMP URL for an earnings calendar request.

String -> DateRange -> String

SECFiling

SEC filing row from FMP's v3 sec_filings endpoint.

Variants

SECFiling {symbol, filing-date, accepted-date, filing-type, link, final-link}

parse-sec-filing

Decode an SEC filing row.

JSONValue -> SECFiling

parse-historical-earnings-calendar-event

Decode a historical earnings calendar row from FMP's v3 symbol endpoint.

JSONValue -> HistoricalEarningsCalendarEvent

RevenueSegmentationPeriod

Re-export the revenue segmentation period enum.

Type

Variants

RevenueSegmentationPeriod

RevenueSegmentValue

Re-export the normalized segment value row.

Type

Variants

RevenueSegmentValue

RevenueSegmentationRow

Re-export the normalized revenue segmentation row.

Type

Variants

RevenueSegmentationRow

parse-economic-observation

Decode an economic indicator observation row.

EconomicIndicatorName -> JSONValue -> EconomicObservation

parse-economic-calendar-event

Decode an economic calendar row.

JSONValue -> EconomicCalendarEvent

parse-treasury-rates

Decode a treasury-rate curve row.

JSONValue -> TreasuryRates

parse-market-risk-premium

Decode a market risk premium row.

JSONValue -> MarketRiskPremium

parse-earnings-calendar-event

Decode an earnings calendar row.

JSONValue -> EarningsCalendarEvent

parse-company-profile

Decode a company profile row.

JSONValue -> CompanyProfile

parse-shares-float

Decode a shares-float row.

JSONValue -> SharesFloat

parse-key-executive

Decode a key-executive row.

JSONValue -> KeyExecutive

parse-price-target-summary

Decode an analyst price-target summary row.

JSONValue -> PriceTargetSummary

parse-analyst-grades-summary

Decode an analyst grades-summary row.

JSONValue -> AnalystGradesSummary

parse-analyst-grade-change

Decode a single analyst grade-change row.

JSONValue -> AnalystGradeChange

parse-analyst-estimate

Decode a core analyst-estimate row.

JSONValue -> AnalystEstimate

parse-rating-snapshot

Decode a ratings snapshot row.

JSONValue -> RatingSnapshot

parse-historical-rating

Decode a historical ratings row.

JSONValue -> HistoricalRating

parse-earnings-report

Decode a historical earnings report row.

JSONValue -> EarningsReport

decode-array

Require an array payload before row-level decoding.

JSONValue -> Result [JSONValue] String

PriceTargetSummary

Analyst price target summary from FMP consensus endpoints.

Variants

PriceTargetSummary {symbol, target-high, target-low, target-median, target-consensus-value, target-consensus-label}

AnalystGradesSummary

Analyst grades consensus summary from FMP's stable grades endpoint.

Variants

AnalystGradesSummary {symbol, strong-buy, buy, hold, sell, strong-sell, consensus}

AnalystGradeChange

Single analyst grade change from FMP's stable grades endpoint.

Variants

AnalystGradeChange {date, company, previous-grade, new-grade, action}

EstimatePeriod

Supported period selection for analyst-estimates queries.

Variants

Annual
Quarter

AnalystEstimate

Core analyst financial estimates row from FMP's stable analyst-estimates endpoint.

Variants

AnalystEstimate {date, estimated-revenue, estimated-ebitda, estimated-net-income, estimated-eps}

RatingSnapshot

Ratings snapshot row from FMP's stable ratings-snapshot endpoint.

Variants

RatingSnapshot {symbol, rating, overall-score, discounted-cash-flow-score, return-on-equity-score, return-on-assets-score, debt-to-equity-score, price-to-earnings-score, price-to-book-score}

HistoricalRating

Historical ratings row from FMP's stable ratings-historical endpoint.

Variants

HistoricalRating {date, symbol, rating, overall-score, discounted-cash-flow-score, return-on-equity-score, return-on-assets-score, debt-to-equity-score, price-to-earnings-score, price-to-book-score}

EarningsReport

Historical earnings report row from FMP's stable earnings endpoint.

Variants

EarningsReport {date, fiscal-date-ending, eps-actual, eps-estimate, revenue-actual, revenue-estimate}

EarningsCallDate

Earnings call transcript metadata row from FMP's v4 transcript-dates endpoint.

Variants

EarningsCallDate {quarter, fiscal-year, call-datetime}

EarningsCallTranscript

Full earnings call transcript row from FMP's stable transcript endpoint.

Variants

EarningsCallTranscript {symbol, period, fiscal-year, call-date, content}

DateRange

Shared date range for calendar-style endpoints.

Variants

DateRange {date-from, date-to}

date-range

Build a calendar date range for date-bounded endpoints.

String -> String -> DateRange

EconomicIndicatorName

Supported FMP macro indicator names.

Variants

GDP
CPI
UnemploymentRate
FederalFundsRate
InflationRate
RetailSales
IndustrialProductionTotalIndex
HousingStarts
ConsumerSentiment
NonFarmPayrolls

EconomicObservation

Economic indicator observation.

Variants

EconomicObservation {indicator, date, value}

EconomicCalendarEvent

Economic calendar event.

Variants

EconomicCalendarEvent {date, country, currency, event, previous, estimate, actual, change, impact, change-percentage}

TreasuryRates

Treasury rate snapshot across the yield curve.

Variants

TreasuryRates {date, rate-1m, rate-2m, rate-3m, rate-6m, rate-1y, rate-2y, rate-3y, rate-5y, rate-7y, rate-10y, rate-20y, rate-30y}

MarketRiskPremium

Market risk premium row used for CAPM / WACC work.

Variants

MarketRiskPremium {country, country-risk-premium, total-equity-risk-premium, risk-free-rate}

EarningsCalendarEvent

Earnings calendar row for all companies reporting in a date range.

Variants

EarningsCalendarEvent {date, symbol, eps-estimate, eps-actual, revenue-estimate, revenue-actual, last-updated}

CompanyProfile

Company profile row from FMP's profile endpoint.

Variants

CompanyProfile {symbol, company-name, currency, exchange-short-name, industry, sector, country, website, ipo-date, market-cap}

SharesFloat

Shares float row from FMP's stable shares-float endpoint.

Variants

SharesFloat {symbol, date, float-shares, outstanding-shares, free-float}

KeyExecutive

Key executive row from FMP's stable key-executives endpoint.

Variants

KeyExecutive {name, title, pay, currency}