Wondering what’s next for npm?Check out our public roadmap! »

    fundamentus-unofficial-api

    1.2.2 • Public • Published

    Fundamentus Unofficial API

    JavaScript Style Guide

    This module provides an api to get data from Brazilian stock shares.

    The truth of source is Fundamentus, a website that provides financial and fundamentalist information about companies listed on the Bovespa.

    Content

    Installation

    $ npm install fundamentus-unofficial-api --save

    Usage

    Importing

    const FundamentusAPI = require('fundamentus-unofficial-api') // CommonJS
    // or
    import FundamentusAPI from 'fundamentus-unofficial-api' // ESM

    Fetching details about share

    const share = await FundamentusAPI.fetch('petr3')

    Output

    • All fields are parsed to its correct data type
      • i.e. '"1,78%" => 0.0178
    • If a field is null, it means there is no data available from Fundamentus
    console.log(share)
    {
      ano2015: -0.0455,
      ano2016: 0.9738,
      ano2017: -0.0018,
      ano2018: 0.5154,
      ano2019: 0.2774,
      ano2020: -0.3891,
      ativo: 926011000000,
      ativoCirculante: 112101000000,
      cotacao: 19.55,
      cresRec5A: 0.009,
      dataUltCot: '08/05/2020',
      dia: 0.0683,
      disponibilidades: 33294000000,
      divBrPorPatrim: 1.19,
      divBruta: 351161000000,
      divLiquida: 317867000000,
      divYield: 0.026,
      ebit: 95991000000,
      ebitPorAtivo: 0.104,
      ebitUltimos3Meses: 28649000000,
      empresa: 'PETROBRAS ON',
      evPorEbit: 5.97,
      evPorEbitda: 3.6,
      giroAtivos: 0.33,
      liquidezCorr: 0.97,
      lpa: 3.08,
      lucroLiquido: 40137000000,
      lucroLiquidoUltimos3Meses: 8153000000,
      margBruta: 0.404,
      margEbit: 0.318,
      margLiquida: 0.136,
      max52Sem: 33.28,
      mes: 0.0483,
      min52Sem: 11.05,
      nroAcoes: 13044500000,
      pPorAtivCircLiq: -0.5,
      pPorAtivos: 0.28,
      pPorCapGiro: -63.03,
      pPorEbit: 2.66,
      pPorL: 6.35,
      pPorVp: 0.86,
      papel: 'PETR3',
      patrimLiq: 295541000000,
      psr: 0.84,
      receitaLiquida: 302245000000,
      receitaLiquidaUltimos3Meses: 72628000000,
      roe: 0.136,
      roic: 0.11,
      setor: 'Petróleo, Gás e Biocombustíveis',
      subsetor: 'Exploração e/ou Refino e Distribuição',      
      tipo: 'ON',
      ultBalancoProcessado: '31/12/2019',
      ultimos12Meses: -0.3437,
      ultimos30Dias: 0.1171,
      valorDaFirma: 572887000000,
      valorDeMercado: 255020000000,
      volMed2M: 607192000,
      vpa: 22.66
    }

    Fetching quotation history

    const quotationHistory = await FundamentusAPI.fetchQuotationHistory('petr3')

    Output

    // console.log(history)
    QuotationHistory {
      share: 'PETR3',
      history: [
        { date: '2020-04-09', quotation: 16.86 },
        ...
      ]
    }

    Methods

    fetchQuotationHistory returns a QuotationHistory instance which we can manipulate to get only a specific range of timeline or quotation value using the following methods:

    • last
    • minDate
    • maxDate
    • minQuotation
    • maxQuotation

    Examples

    const quotationHistory = await FundamentusAPI.fetchQuotationHistory('petr3')
     
    // Returns the history range which the quotation value was, at least, R$11.43 since January 1st, 2020
    quotationHistory.minQuotation(11.43).minDate('2020-01-01')
    const quotationHistory = await FundamentusAPI.fetchQuotationHistory('petr3')
     
    // Returns the history in the last 10 days
    quotationHistory.last(10)

    Fetching earnings history

    const earningsHistory = await FundamentusAPI.fetchEarningsHistory('petr3')

    Output

    // console.log(history)
    EarningsHistory {
      share: 'PETR3',
      history: [
        { date: '2008-04-04', value: 0.05, type: 'DIVIDENDO', perShare: 1 },
        ...
      ]
    }

    Methods

    fetchEarningsHistory returns a EarningsHistory instance which we can manipulate to get only a specific range of timeline, value or by type using the following methods:

    • minDate
    • maxDate
    • minValue
    • maxValue
    • filterByType

    Examples

    const earningsHistory = await FundamentusAPI.fetchEarningsHistory('petr3')
     
    // Returns all the earnings of 2019
    earningsHistory.minDate('2019-01-01').maxDate('2019-12-31')
    const earningsHistory = await FundamentusAPI.fetchEarningsHistory('petr3')
     
    // Returns earnings by dividends with min value of 0.5
    earningsHistory.filterByType('DIVIDENDO').minValue(0.5)

    Getting help

    If you need help, want to make a suggestion or encounter a bug, please contact me:
    https://github.com/margato/fundamentus-unofficial-api/issues

    Install

    npm i fundamentus-unofficial-api

    DownloadsWeekly Downloads

    18

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    15.8 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar