Finnhub API

https://finnhub.io/docs/api/market-news
Admin
Finnhub API is a comprehensive financial data platform providing real-time and historical market...
Tokens:85,662
Snippets:493
Trust Score:9.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Market Status Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for a market status request.

```json
{
  "exchange": "US",
  "holiday": null,
  "isOpen": false,
  "session": "pre-market",
  "timezone": "America/New_York",
  "t": 1697018041
}
```

--------------------------------

### ETF Equity Allocation Response Example

Source: https://finnhub.io/docs/api/market-news

Example JSON response structure for the equity allocation endpoint.

```json
{
  "data": {
    "largeBlend": 38.1,
    "largeGrowth": 20.41,
    "largeValue": 22.03,
    "midBlend": 8.67,
    "midGrowth": 3.88,
    "midValue": 5.94,
    "smallBlend": 0.52,
    "smallGrowth": 0.05,
    "smallValue": 0.4
  },
  "symbol": "SPY"
}
```

--------------------------------

### Company Peers Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for the company peers endpoint.

```json
[
  "AAPL",
  "EMC",
  "HPQ",
  "DELL",
  "WDC",
  "HPE",
  "NTAP",
  "CPQ",
  "SNDK",
  "SEG"
]
```

--------------------------------

### Market Holiday Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for a market holiday request.

```json
{
  "data": [
    {
      "eventName": "Christmas",
      "atDate": "2023-12-25",
      "tradingHour": ""
    },
    {
      "eventName": "Independence Day",
      "atDate": "2023-07-03",
      "tradingHour": "09:30-13:00"
    }
  ],
  "exchange": "US",
  "timezone": "America/New_York"
}
```

--------------------------------

### Net Income Estimates API Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for the net income estimates endpoint.

```json
{
  "data": [
    {
      "numberAnalysts": 31,
      "period": "2020-06-30",
      "netIncomeAvg": 58800500000,
      "netIncomeHigh": 64060000000,
      "netIncomeLow": 54072000000,
      "quarter": 3,
      "year": 2020
    },
    {
      "numberAnalysts": 31,
      "period": "2020-03-31",
      "netIncomeAvg": 61287300000,
      "netIncomeHigh": 66557000000,
      "netIncomeLow": 54871000000,
      "quarter": 2,
      "year": 2020
    }
  ],
  "freq": "quarterly",
  "symbol": "AAPL"
}
```

--------------------------------

### ETF Country Exposure Response Example

Source: https://finnhub.io/docs/api/market-news

Example JSON response structure for the country exposure endpoint.

```json
{
  "countryExposure": [
    {
      "country": "United States of America (the)",
      "exposure": 97.02
    },
    {
      "country": "Ireland",
      "exposure": 1.65
    },
    {
      "country": "United Kingdom of Great Britain and Northern Ireland (the)",
      "exposure": 0.88
    },
    {
      "country": "Switzerland",
      "exposure": 0.41
    },
    {
      "country": "Bermuda",
      "exposure": 0.03
    }
  ],
  "symbol": "SPY"
}
```

--------------------------------

### GET /forex/exchange

Source: https://finnhub.io/docs/api/introduction

Lists all supported forex exchanges.

```APIDOC
## GET /forex/exchange

### Description
List supported forex exchanges.

### Method
GET

### Endpoint
/forex/exchange

### Response
#### Success Response (200)
- **exchanges** (array) - List of supported exchange names

### Response Example
[
  "oanda",
  "fxcm",
  "forex.com",
  "ic markets",
  "fxpro"
]
```

--------------------------------

### GET /quote

Source: https://finnhub.io/docs/api/introduction

Retrieves real-time quote data for US stocks.

```APIDOC
## GET /quote

### Description
Get real-time quote data for US stocks.

### Method
GET

### Endpoint
/quote

### Parameters
#### Query Parameters
- **symbol** (string) - Required - Symbol

### Response
#### Success Response (200)
- **c** (number) - Current price
- **d** (number) - Change
- **dp** (number) - Percent change
- **h** (number) - High price of the day
- **l** (number) - Low price of the day
- **o** (number) - Open price of the day
- **pc** (number) - Previous close price

### Response Example
{
  "c": 261.74,
  "h": 263.31,
  "l": 260.68,
  "o": 261.07,
  "pc": 259.45,
  "t": 1582641000
}
```

--------------------------------

### Symbol Lookup Response Example

Source: https://finnhub.io/docs/api/introduction

JSON structure returned by the symbol lookup endpoint.

```json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "count": 4,
  "result": [
    {
      "description": "APPLE INC",
      "displaySymbol": "AAPL",
      "symbol": "AAPL",
      "type": "Common Stock"
    },
    {
      "description": "APPLE INC",
      "displaySymbol": "AAPL.SW",
      "symbol": "AAPL.SW",
      "type": "Common Stock"
    },
    {
      "description": "APPLE INC",
      "displaySymbol": "APC.BE",
      "symbol": "APC.BE",
      "type": "Common Stock"
    },
    {
      "description": "APPLE INC",
      "displaySymbol": "APC.DE",
      "symbol": "APC.DE",
      "type": "Common Stock"
    }
  ]
}

```

--------------------------------

### Sample API Response

Source: https://finnhub.io/docs/api/introduction

Example JSON structure returned by the press releases endpoint.

```json
{
  "majorDevelopment": [
    {
      "symbol": "AAPL",
      "datetime": "2020-08-04 17:06:32",
      "headline": "27-inch iMac Gets a Major Update",
      "description": "CUPERTINO, Calif.--(BUSINESS WIRE)-- Apple today announced a major update to its 27-inch iMac®. By far the most powerful and capable iMac ever, it features faster Intel processors up to 10 cores, double the memory capacity, next-generation AMD graphics, superfast SSDs across the line with four times the storage capacity, a new nano-texture glass option for an even more stunning Retina® 5K display, a 1080p FaceTime® HD camera, higher fidelity speakers, and studio-quality mics. For the consumer using their iMac all day, every day, to the aspiring creative looking for inspiration, to the serious pro pushing the limits of their creativity, the new 27-inch iMac delivers the ultimate desktop experience that is now better in every way."
    },
    {
      "symbol": "AAPL",
      "datetime": "2020-03-28 09:41:23",
      "headline": "Apple Central World Opens Friday in Thailand",
      "description": "BANGKOK--(BUSINESS WIRE)-- Apple® today previewed Apple Central World, its second and largest retail location in Thailand. Nestled in the heart of Ratchaprasong, Bangkok’s iconic intersection, the store provides a completely new and accessible destination within the lively city. Apple Central World’s distinctive architecture is brought to life with the first-ever all-glass design, housed under a cantilevered Tree Canopy roof. Once inside, customers can travel between two levels via a spiral staircase that wraps around a timber core, or riding a unique cylindrical elevator clad in mirror-polished stainless steel. Guests can enter from the ground or upper level, which provides a direct connection to the Skytrain and the city’s largest shopping center. The outdoor plaza offers a place for the community to gather, with benches and large Terminalia trees surrounding the space."
    }
  ],
   "symbol": "AAPL"
}
```

--------------------------------

### GET /bond/yield-curve

Source: https://finnhub.io/docs/api/market-news

Retrieves yield curve data for Treasury bonds.

```APIDOC
## GET /bond/yield-curve

### Description
Get yield curve data for Treasury bonds.

### Method
GET

### Endpoint
/bond/yield-curve

### Parameters
#### Query Parameters
- **code** (string) - Required - Bond's code.

### Response
#### Success Response (200)
- **code** (string) - Bond's code
- **data** (array) - Array of data containing date (d) and value (v)

### Response Example
{
  "code": "10y",
  "data": [
    {
      "d": "2022-10-31",
      "v": 4.1
    },
    {
      "d": "2022-11-01",
      "v": 4.07
    }
  ]
}
```

--------------------------------

### Sample Quote Response

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for a stock quote request.

```json
{
  "c": 261.74,
  "h": 263.31,
  "l": 260.68,
  "o": 261.07,
  "pc": 259.45,
  "t": 1582641000 
}
```

--------------------------------

### Retrieve company basic financials using Python

Source: https://finnhub.io/docs/api/introduction

Initializes the Finnhub client with an API key and fetches all available metrics for a specified symbol.

```python
1
2
3
4
5
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.company_basic_financials('AAPL', 'all'))
```

--------------------------------

### Sample API Response for Upgrades/Downgrades

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure containing analyst rating changes for a company.

```json
[
  {
    "symbol": "BYND",
    "gradeTime": 1567728000,
    "company": "DA Davidson",
    "fromGrade": "",
    "toGrade": "Underperform",
    "action": "init"
  },
  {
    "symbol": "BYND",
    "gradeTime": 1566259200,
    "company": "JP Morgan",
    "fromGrade": "Neutral",
    "toGrade": "Overweight",
    "action": "up"
  },
  {
    "symbol": "BYND",
    "gradeTime": 1564704000,
    "company": "Bank of America",
    "fromGrade": "",
    "toGrade": "Neutral",
    "action": "reit"
  }
]
```

--------------------------------

### News Sentiment Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for the news sentiment endpoint.

```json
{
  "buzz": {
    "articlesInLastWeek": 20,
    "buzz": 0.8888,
    "weeklyAverage": 22.5
  },
  "companyNewsScore": 0.9166,
  "sectorAverageBullishPercent": 0.6482,
  "sectorAverageNewsScore": 0.5191,
  "sentiment": {
    "bearishPercent": 0,
    "bullishPercent": 1
  },
  "symbol": "V"
}
```

--------------------------------

### Retrieve Company Newsroom Articles with Python

Source: https://finnhub.io/docs/api/introduction

Initializes the Finnhub client and fetches newsroom articles for a specific company symbol.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.newsroom('AAPL'))
```

--------------------------------

### IPO Calendar Sample Response

Source: https://finnhub.io/docs/api/introduction

Example JSON structure returned by the IPO calendar endpoint.

```json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "ipoCalendar": [
    {
      "date": "2020-04-03",
      "exchange": "NASDAQ Global",
      "name": "ZENTALIS PHARMACEUTICALS, LLC",
      "numberOfShares": 7650000,
      "price": "16.00-18.00",
      "status": "expected",
      "symbol": "ZNTL",
      "totalSharesValue": 158355000
    },
    {
      "date": "2020-04-01",
      "exchange": "NASDAQ Global",
      "name": "WIMI HOLOGRAM CLOUD INC.",
      "numberOfShares": 5000000,
      "price": "5.50-7.50",
      "status": "expected",
      "symbol": "WIMI",
      "totalSharesValue": 43125000
    },
  ]
}
```

--------------------------------

### GET /bond/profile

Source: https://finnhub.io/docs/api/market-news

Retrieves general information of a bond. You can query by FIGI, ISIN or CUSIP.

```APIDOC
## GET /bond/profile

### Description
Get general information of a bond. You can query by FIGI, ISIN or CUSIP.

### Method
GET

### Endpoint
/bond/profile

### Parameters
#### Query Parameters
- **isin** (string) - Optional - ISIN
- **cusip** (string) - Optional - CUSIP
- **figi** (string) - Optional - FIGI

### Response
#### Success Response (200)
- **amountOutstanding** (number) - Outstanding amount.
- **asset** (string) - Asset.
- **assetType** (string) - Asset.
- **bondType** (string) - Bond type.
- **callable** (boolean) - Callable.
- **coupon** (number) - Coupon.
- **couponType** (string) - Coupon type.
- **cusip** (string) - Cusip.
- **datedDate** (string) - Dated date.
- **debtType** (string) - Bond type.
- **figi** (string) - FIGI.
- **firstCouponDate** (string) - First coupon date.
- **industryGroup** (string) - Industry.
- **industrySubGroup** (string) - Sub-Industry.
- **isin** (string) - ISIN.
- **issueDate** (string) - Issue date.
- **maturityDate** (string) - Period.
- **offeringPrice** (number) - Offering price.
- **originalOffering** (number) - Offering amount.
- **paymentFrequency** (string) - Payment frequency.
- **securityLevel** (string) - Security level.

### Response Example
{
  "isin": "US912810TD00",
  "cusip": "",
  "figi": "BBG0152KFHS6",
  "coupon": 2.25,
  "maturityDate": "2052-02-15",
  "offeringPrice": 100,
  "issueDate": "2022-03-15",
  "bondType": "US Government",
  "debtType": "",
  "industryGroup": "Government",
  "industrySubGroup": "U.S. Treasuries",
  "asset": "",
  "assetType": "",
  "datedDate": "2022-02-15",
  "firstCouponDate": "2022-08-15",
  "originalOffering": 20000000000,
  "amountOutstanding": 36914000000,
  "paymentFrequency": "Semi-Annual",
  "securityLevel": "",
  "callable": null,
  "couponType": "",
  "dayCount": ""
}
```

--------------------------------

### Search In Filing Request

Source: https://finnhub.io/docs/api/introduction

Example of how to perform a POST request to the search-in-filing endpoint using Python.

```python
import requests
import json

url = "https://finnhub.io/api/v1/global-filings/search-in-filing?token="

payload = json.dumps({
  "query": "covid",
  "filingId": "AAPL_1113753"
})

response = requests.request("POST", url,  data=payload)

print(response.json())
```

--------------------------------

### Mutual Fund EET Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for the EET data endpoint.

```json
{
   "data":{
      "boardGenderDiversityConsidered":true,
      "carbonFootprintScope123Considered":false,
      "carbonFootprintScope12Considered":false,
      "clientSustainabilityPreferencesConsidered":true,
      "controversialWeaponsConsidered":true,
      "energyConsumptionIntensityNACEAConsidered":false,
      "exposuretoEnergyEfficientRealEstateAssetsConsidered":false,
      "exposuretoFossilFuelSectorConsidered":false,
      "exposuretoFossilFuelsExtractionStorageTransportManufactureConsidered":false,
      "greenhouseGasEmissionsScope1Considered":false,
      "greenhouseGasEmissionsScope2Considered":false,
      "greenhouseGasEmissionsScope3Considered":false,
   },
   "isin":"LU2036931686"
}
```

--------------------------------

### Get Crypto Profile

Source: https://finnhub.io/docs/api/market-news

Retrieves the profile information for a specific cryptocurrency symbol. Requires premium access.

```python
1
2
3
4
5
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.crypto_profile('BTC'))
```

--------------------------------

### GET /mutual-fund/eet-pai

Source: https://finnhub.io/docs/api/market-news

Retrieves EET PAI data for EU funds based on the provided ISIN.

```APIDOC
## GET /mutual-fund/eet-pai

### Description
Get EET PAI data for EU funds.

### Method
GET

### Endpoint
/mutual-fund/eet-pai

### Parameters
#### Query Parameters
- **isin** (string) - Required - ISIN of the fund.

### Response
#### Success Response (200)
- **data** (object) - EET PAI data.
- **isin** (string) - ISIN of the fund.

#### Response Example
{
   "data":{
      "airPollutantEmissionsCoveredHoldings":27.94263,
      "airPollutantEmissionsEligibleHoldings":490.89858
   },
   "isin":"LU2036931686"
}
```

--------------------------------

### Run Pattern Recognition with Python

Source: https://finnhub.io/docs/api/introduction

Initializes the Finnhub client and executes a pattern recognition scan for a specific symbol and resolution.

```python
1
2
3
4
5
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.pattern_recognition('AAPL', 'D'))
```

--------------------------------

### EBIT Estimates API Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for the EBIT estimates endpoint.

```json
{
  "data": [
    {
      "numberAnalysts": 31,
      "period": "2020-06-30",
      "ebitAvg": 58800500000,
      "ebitHigh": 64060000000,
      "ebitLow": 54072000000
      "quarter": 3,
      "year": 2020,
    },
    {
      "numberAnalysts": 31,
      "period": "2020-03-31",
      "ebitAvg": 61287300000,
      "ebitHigh": 66557000000,
      "ebitLow": 54871000000,
      "quarter": 2,
      "year": 2020,
    }
  ],
  "freq": "quarterly",
  "symbol": "AAPL"
}
```

--------------------------------

### GET /stock/earnings-call-live

Source: https://finnhub.io/docs/api/market-news

Retrieves a list of earnings call events that support live streaming within a specified date range.

```APIDOC
## GET /stock/earnings-call-live

### Description
Stream live earnings calls with data provided in the calendar. The data will be available in m3u8 format. mp3 files will be available once the calls finish in the recording field.

### Method
GET

### Endpoint
/stock/earnings-call-live

### Parameters
#### Query Parameters
- **from** (string) - Optional - From date YYYY-MM-DD.
- **to** (string) - Optional - To date YYYY-MM-DD.
- **symbol** (string) - Optional - Filter by symbol (e.g., AAPL).

### Response
#### Success Response (200)
- **event** (array) - Array of earnings call events that support live streaming.
  - **symbol** (string) - Symbol.
  - **year** (integer) - Earnings year.
  - **quarter** (integer) - Earnings quarter.
  - **event** (string) - Event name.
  - **time** (string) - Date time in UTC.
  - **liveAudio** (string) - Live audio streaming file.
  - **recording** (string) - Recording in mp3 format.

### Response Example
{
  "event": [
    {
      "symbol": "NVDA",
      "year": 2025,
      "quarter": 3,
      "event": "NVDA - Earnings call Q3 year",
      "time": "2024-11-20 22:00:00",
      "liveAudio": "https://live.finnhub.io/hls/2063191eb8563e1645fe3bde2b057511dce4f8a0fb39a2fb9/audio.m3u8",
      "recording": ""
    }
  ]
}
```

--------------------------------

### USA Spending API Response Format

Source: https://finnhub.io/docs/api/market-news

Example JSON response structure returned by the USA Spending endpoint.

```json
{
  "data":[
    {
      "symbol":"AAPL",
      "recipientName":"APPLE INC.",
      "recipientParentName":"APPLE INC.",
      "country":"USA",
      "totalValue":4238,
      "actionDate":"2021-11-12",
      "performanceStartDate":"2021-11-12",
      "performanceEndDate":"2021-12-10",
      "awardingAgencyName":"SMITHSONIAN INSTITUTION (SI)",
      "awardingSubAgencyName":"SMITHSONIAN INSTITUTION",
      "awardingOfficeName":"SMITHSONIAN ASTROPHYSICAL OBSERVATORY",
      "performanceCountry":"USA",
      "performanceCity":"CUPERTINO",
      "performanceCounty":"SANTA CLARA",
      "performanceState":"CALIFORNIA",
      "performanceZipCode":"950140642",
      "performanceCongressionalDistrict":"17",
      "awardDescription":"MACBOOK PRO",
      "naicsCode":"334111",
      "permalink":"https://www.usaspending.gov/award/CONT_AWD_33131222P00465925_3300_-NONE-_-NONE-/"
    }
  ],
  "symbol":"AAPL"
}
```

--------------------------------

### GET /stock/lobbying

Source: https://finnhub.io/docs/api/market-news

Retrieves a list of reported lobbying activities for a given stock symbol between two dates.

```APIDOC
## GET /stock/lobbying

### Description
Get a list of reported lobbying activities in the Senate and the House for a specific company.

### Method
GET

### Endpoint
/stock/lobbying

### Parameters
#### Query Parameters
- **symbol** (string) - Required - Symbol of the company.
- **from** (string) - Required - Start date in YYYY-MM-DD format.
- **to** (string) - Required - End date in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **data** (array) - Array of lobbying activities.
- **symbol** (string) - The requested stock symbol.
```

--------------------------------

### GET /stock/usa-spending

Source: https://finnhub.io/docs/api/market-news

Retrieves a list of government spending activities for a specific public company within a given date range.

```APIDOC
## GET /stock/usa-spending

### Description
Get a list of government's spending activities from USASpending dataset for public companies.

### Method
GET

### Endpoint
/stock/usa-spending

### Parameters
#### Query Parameters
- **symbol** (string) - Required - Symbol of the company.
- **from** (string) - Required - From date YYYY-MM-DD. Filter for actionDate.
- **to** (string) - Required - To date YYYY-MM-DD. Filter for actionDate.

### Response
#### Success Response (200)
- **data** (array) - Array of government's spending data points.
- **symbol** (string) - Symbol.

#### Response Example
{
  "data": [
    {
      "symbol": "AAPL",
      "recipientName": "APPLE INC.",
      "recipientParentName": "APPLE INC.",
      "country": "USA",
      "totalValue": 4238,
      "actionDate": "2021-11-12",
      "performanceStartDate": "2021-11-12",
      "performanceEndDate": "2021-12-10",
      "awardingAgencyName": "SMITHSONIAN INSTITUTION (SI)",
      "awardingSubAgencyName": "SMITHSONIAN INSTITUTION",
      "awardingOfficeName": "SMITHSONIAN ASTROPHYSICAL OBSERVATORY",
      "performanceCountry": "USA",
      "performanceCity": "CUPERTINO",
      "performanceCounty": "SANTA CLARA",
      "performanceState": "CALIFORNIA",
      "performanceZipCode": "950140642",
      "performanceCongressionalDistrict": "17",
      "awardDescription": "MACBOOK PRO",
      "naicsCode": "334111",
      "permalink": "https://www.usaspending.gov/award/CONT_AWD_33131222P00465925_3300_-NONE-_-NONE-/"
    }
  ],
  "symbol": "AAPL"
}
```

--------------------------------

### Retrieve Capex Estimates with Python

Source: https://finnhub.io/docs/api/introduction

Initializes the Finnhub client and fetches quarterly capex estimates for a specific stock symbol.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.company_capex_estimates('AAPL', freq='quarterly'))
```

--------------------------------

### Senate Lobbying API Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response containing an array of lobbying activities for the requested symbol.

```json
{
  "data":[
    {
      "symbol":"AAPL",
      "name":"APPLE, INC.",
      "description":"Hardware and software maunfacturer",
      "country":"US",
      "uuid":"db75bb6f-162a-433a-a997-a679eb4c6af6",
      "year":2020,
      "period":"fourth_quarter",
      "type":"Q4",
      "documentUrl":"https://lda.senate.gov/filings/public/filing/db75bb6f-162a-433a-a997-a679eb4c6af6/print/",
      "income":40000,
      "expenses":null,
      "postedName":"",
      "dtPosted":"",
      "clientId":"173094",
      "registrantId":"86196",
      "senateId":"86196-173094",
      "houseRegistrantId":"36548"
    },
    {
      "symbol":"AAPL",
      "name":"APPLE INC",
      "description":"",
      "country":"US",
      "uuid":"cad6db2f-c3ca-4b9d-bc24-4c56fc7eaadb",
      "year":2020,
      "period":"fourth_quarter",
      "type":"Q4",
      "documentUrl":"https://lda.senate.gov/filings/public/filing/cad6db2f-c3ca-4b9d-bc24-4c56fc7eaadb/print/",
      "income":null,
      "expenses":1450000,
      "postedName":"",
      "dtPosted":"",
      "clientId":"103979",
      "registrantId":"4152",
      "senateId":"4152-103979",
      "houseRegistrantId":"31450"
    }
  ],
  "symbol":"AAPL"
}
```

--------------------------------

### Retrieve SEC Filings with Python

Source: https://finnhub.io/docs/api/introduction

Example usage of the Finnhub client to fetch filings for a specific symbol within a date range.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.filings(symbol='AAPL', _from="2020-01-01", to="2020-06-11"))
```

--------------------------------

### Mutual Fund EET PAI Response Example

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for the EET PAI data endpoint.

```json
{
   "data":{
      "airPollutantEmissionsCoveredHoldings":27.94263,
      "airPollutantEmissionsEligibleHoldings":490.89858,
      "airPollutantEmissionsNumberHoldingsCovered":14,
      "airPollutantEmissionsPctPortfolioCoverage":4.57,
      "airPollutantEmissionsPctPortfolioEligibleAssets":79.65,
      "airPollutantEmissionsTonnesPerEURm":1.28271,
      "antiHumanTraffickingNumberHoldingsCovered":67,
   },
   "isin":"LU2036931686"
}
```

--------------------------------

### Retrieve Company Profile with Python

Source: https://finnhub.io/docs/api/introduction

Initializes the Finnhub client and fetches profile data for a specific stock symbol.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.company_profile(symbol='AAPL'))
```

--------------------------------

### Retrieve Country Metadata with Python

Source: https://finnhub.io/docs/api/introduction

Initializes the Finnhub client and fetches the list of countries and their metadata.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.country())
```

--------------------------------

### GET /economic/code

Source: https://finnhub.io/docs/api/introduction

Lists codes of supported economic data.

```APIDOC
## GET /economic/code

### Description
List codes of supported economic data.

### Method
GET

### Endpoint
/economic/code

### Response
#### Success Response (200)
- **code** (string) - Finnhub economic code used to get historical data
- **country** (string) - Country
- **name** (string) - Indicator name
- **unit** (string) - Unit

### Response Example
[
  {
    "code": "MA-USA-656880",
    "country": "USA",
    "name": "1-Day Repo Rate",
    "unit": "%"
  }
]
```

--------------------------------

### Sample Forex Exchanges Response

Source: https://finnhub.io/docs/api/introduction

Example JSON response containing a list of supported forex exchange identifiers.

```json
[
  "oanda",
  "fxcm",
  "forex.com",
  "ic markets",
  "fxpro"
]
```

--------------------------------

### GET /country

Source: https://finnhub.io/docs/api/introduction

Retrieves a list of all countries and their associated metadata.

```APIDOC
## GET /country

### Description
List all countries and metadata.

### Method
GET

### Endpoint
/country

### Response
#### Success Response (200)
- **code2** (string) - Alpha 2 code
- **code3** (string) - Alpha 3 code
- **codeNo** (string) - UN code
- **country** (string) - Country name
- **countryRiskPremium** (number) - Country risk premium
- **currency** (string) - Currency name
- **currencyCode** (string) - Currency code
- **defaultSpread** (number) - Default spread
- **equityRiskPremium** (number) - Equity risk premium
- **logo** (string) - Flag image
- **rating** (string) - Moody's credit risk rating
- **region** (string) - Region
- **subRegion** (string) - Sub-Region

#### Response Example
[
  {
    "code2": "US",
    "code3": "USA",
    "codeNo": "840",
    "country": "United States",
    "countryRiskPremium": 0,
    "currency": "US Dollar",
    "currencyCode": "USD",
    "defaultSpread": 0,
    "equityRiskPremium": 5,
    "rating": "Aaa",
    "region": "Americas",
    "subRegion": "Northern America",
    "logo": "https://static2.finnhub.io/file/publicdatany/finnhubimage/country_logo/us.svg"
  }
]
```

--------------------------------

### Sample Forex Symbols Response

Source: https://finnhub.io/docs/api/introduction

Example JSON response containing symbol descriptions, display names, and unique identifiers.

```json
[
  {
    "description": "IC MARKETS Euro vs US Dollar EURUSD",
    "displaySymbol": "EUR/USD",
    "symbol": "IC MARKETS:1"
  },
  {
    "description": "IC MARKETS Australian vs US Dollar AUDUSD",
    "displaySymbol": "AUD/USD",
    "symbol": "IC MARKETS:5"
  },
  {
    "description": "IC MARKETS British Pound vs US Dollar GBPUSD",
    "displaySymbol": "GBP/USD",
    "symbol": "IC MARKETS:2"
  }]
```

--------------------------------

### Retrieve Financials As Reported with Python

Source: https://finnhub.io/docs/api/introduction

Initializes the Finnhub client and retrieves annual financial reports for a specific symbol.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.financials_reported(symbol='AAPL', freq='annual'))
```

--------------------------------

### GET /crypto/profile

Source: https://finnhub.io/docs/api/introduction

Retrieves the profile information for a specific cryptocurrency.

```APIDOC
## GET /crypto/profile

### Description
Get crypto's profile. Premium access is required.

### Method
GET

### Endpoint
/crypto/profile

### Parameters
#### Query Parameters
- **symbol** (string) - Required - Crypto symbol such as BTC or ETH.

### Response
#### Success Response (200)
- **circulatingSupply** (number) - Circulating supply
- **description** (string) - Description
- **launchDate** (string) - Launch date
- **logo** (string) - Logo image
- **longName** (string) - Long name
- **marketCap** (number) - Market capitalization
- **maxSupply** (number) - Max supply
- **name** (string) - Name
- **proofType** (string) - Proof type
- **totalSupply** (number) - Total supply
- **website** (string) - Project's website
```

--------------------------------

### Retrieve Stock Upgrades and Downgrades in Python

Source: https://finnhub.io/docs/api/introduction

Uses the Finnhub client to fetch upgrade/downgrade data for a specific symbol within a date range.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.upgrade_downgrade(symbol='AAPL', _from='2020-01-01', to='2020-06-30'))
```

--------------------------------

### GET /crypto/exchange

Source: https://finnhub.io/docs/api/introduction

Retrieves a list of supported cryptocurrency exchanges.

```APIDOC
## GET /crypto/exchange

### Description
List supported crypto exchanges.

### Method
GET

### Endpoint
/crypto/exchange

### Response
#### Success Response (200)
- **exchanges** (array) - A list of supported crypto exchange names.

### Response Example
[
  "KRAKEN",
  "COINBASE",
  "BINANCE"
]
```

--------------------------------

### GET /bond/tick

Source: https://finnhub.io/docs/api/introduction

Retrieves trade-level tick data for bonds.

```APIDOC
## GET /bond/tick

### Description
Get trade-level data for bonds, specifically supporting FINRA Trace datasets.

### Method
GET

### Endpoint
/bond/tick

### Parameters
#### Query Parameters
- **isin** (string) - Required - ISIN.
- **date** (string) - Required - Date in format YYYY-MM-DD.
- **limit** (integer) - Required - Limit number of ticks returned (Max 25000).
- **skip** (integer) - Required - Number of ticks to skip.
- **exchange** (string) - Required - Exchange identifier (e.g., 'trace').

### Response
#### Success Response (200)
- **ats** (string) - ATS flag.
- **c** (array) - List of trade conditions.
- **count** (integer) - Number of ticks returned.
- **cp** (array) - List of counterparty values.
- **p** (array) - List of price data.
- **rp** (array) - List of reporting party values.
- **si** (array) - List of side (Buy/sell) values.
- **skip** (integer) - Number of ticks skipped.
- **t** (array) - List of timestamps in UNIX ms.
- **total** (integer) - Total number of ticks for that date.
- **v** (array) - List of volume data.
- **y** (array) - List of yield data.

### Response Example
{
  "c": [[], [], []],
  "count": 3,
  "cp": ["3", "1", "1"],
  "p": [100.592, 100.492, 100.234],
  "si": ["2", "2", "2"],
  "skip": 6,
  "t": [1660929161000, 1660929161000, 1660929778000],
  "total": 211,
  "v": [3000, 3000, 50000]
}
```

--------------------------------

### Retrieve Revenue Estimates with Python

Source: https://finnhub.io/docs/api/introduction

Use the Finnhub client to fetch revenue estimates for a specific symbol. Requires a valid API key.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.company_revenue_estimates('TSLA', freq='quarterly'))
```

--------------------------------

### Support and Resistance Response Format

Source: https://finnhub.io/docs/api/introduction

Example JSON response structure for the support and resistance endpoint.

```json
{
  "levels": [
    1.092360019683838,
    1.1026300191879272,
    1.113450050354004,
    1.1233500242233276,
    1.134719967842102,
    1.1513700485229492
  ]
}
```

--------------------------------

### GET /stock/candle

Source: https://finnhub.io/docs/api/introduction

Retrieves candlestick data (OHLCV) for stocks.

```APIDOC
## GET /stock/candle

### Description
Get candlestick data (OHLCV) for stocks. Daily data is adjusted for splits, while intraday data remains unadjusted.

### Method
GET

### Endpoint
/stock/candle

### Parameters
#### Query Parameters
- **symbol** (string) - Required - Symbol
- **resolution** (string) - Required - Supported resolution includes 1, 5, 15, 30, 60, D, W, M
- **from** (integer) - Required - UNIX timestamp. Interval initial value.
- **to** (integer) - Required - UNIX timestamp. Interval end value.

### Response
#### Success Response (200)
- **c** (array) - List of close prices
- **h** (array) - List of high prices
- **l** (array) - List of low prices
- **o** (array) - List of open prices
- **s** (string) - Status of the response (ok or no_data)
- **t** (array) - List of timestamps
- **v** (array) - List of volume data

### Response Example
{
  "c": [217.68, 221.03, 219.89],
  "h": [222.49, 221.5, 220.94],
  "l": [217.19, 217.1402, 218.83],
  "o": [221.03, 218.55, 220],
  "s": "ok",
  "t": [1569297600, 1569384000, 1569470400],
  "v": [33463820, 24018876, 20730608]
}
```

--------------------------------

### Sample JSON response for basic financials

Source: https://finnhub.io/docs/api/introduction

Example structure of the JSON response containing series data, key metrics, and metric types.

```json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
   "series": {
    "annual": {
      "currentRatio": [
        {
          "period": "2019-09-28",
          "v": 1.5401
        },
        {
          "period": "2018-09-29",
          "v": 1.1329
        }
      ],
      "salesPerShare": [
        {
          "period": "2019-09-28",
          "v": 55.9645
        },
        {
          "period": "2018-09-29",
          "v": 53.1178
        }
      ],
      "netMargin": [
        {
          "period": "2019-09-28",
          "v": 0.2124
        },
        {
          "period": "2018-09-29",
          "v": 0.2241
        }
      ]
    }
  },
  "metric": {
    "10DayAverageTradingVolume": 32.50147,
    "52WeekHigh": 310.43,
    "52WeekLow": 149.22,
    "52WeekLowDate": "2019-01-14",
    "52WeekPriceReturnDaily": 101.96334,
    "beta": 1.2989,
  },
  "metricType": "all",
  "symbol": "AAPL"
}
```

--------------------------------

### GET /stock/ebitda-estimate

Source: https://finnhub.io/docs/api/introduction

Retrieves the company's EBITDA estimates.

```APIDOC
## GET /stock/ebitda-estimate

### Description
Get company's ebitda estimates.

### Method
GET

### Endpoint
/stock/ebitda-estimate

### Parameters
#### Query Parameters
- **symbol** (string) - Required - Symbol of the company: AAPL.
- **freq** (string) - Optional - Can take 1 of the following values: annual, quarterly. Default to quarterly.

### Response
#### Success Response (200)
- **data** (array) - List of estimates
- **freq** (string) - Frequency: annual or quarterly.
- **symbol** (string) - Company symbol.

#### Response Example
{
  "data": [
    {
      "numberAnalysts": 31,
      "period": "2020-06-30",
      "ebitdaAvg": 58800500000,
      "ebitdaHigh": 64060000000,
      "ebitdaLow": 54072000000,
      "quarter": 3,
      "year": 2020
    }
  ],
  "freq": "quarterly",
  "symbol": "AAPL"
}
```

--------------------------------

### Sample Company Profile Response

Source: https://finnhub.io/docs/api/introduction

Example JSON object returned by the company profile endpoint containing company metadata.

```json
{
  "country": "US",
  "currency": "USD",
  "exchange": "NASDAQ/NMS (GLOBAL MARKET)",
  "ipo": "1980-12-12",
  "marketCapitalization": 1415993,
  "name": "Apple Inc",
  "phone": "14089961010",
  "shareOutstanding": 4375.47998046875,
  "ticker": "AAPL",
  "weburl": "https://www.apple.com/",
  "logo": "https://static.finnhub.io/logo/87cb30d8-80df-11ea-8951-00000000092a.png",
  "finnhubIndustry":"Technology"
}
```

--------------------------------

### GET /stock/eps-estimate

Source: https://finnhub.io/docs/api/introduction

Retrieves the company's EPS estimates.

```APIDOC
## GET /stock/eps-estimate

### Description
Get company's EPS estimates.

### Method
GET

### Endpoint
/stock/eps-estimate

### Parameters
#### Query Parameters
- **symbol** (string) - Required - Symbol of the company: AAPL.
- **freq** (string) - Optional - Can take 1 of the following values: annual, quarterly. Default to quarterly.

### Response
#### Success Response (200)
- **data** (array) - List of estimates
- **freq** (string) - Frequency: annual or quarterly.
- **symbol** (string) - Company symbol.

#### Response Example
{
  "data": [
    {
      "epsAvg": 2.65,
      "epsHigh": 2.98,
      "epsLow": 2.05,
      "numberAnalysts": 35,
      "period": "2020-06-30",
      "quarter": 3,
      "year": 2020
    }
  ],
  "freq": "quarterly",
  "symbol": "AAPL"
}
```

--------------------------------

### Retrieve Pretax Income Estimates with Python

Source: https://finnhub.io/docs/api/introduction

Uses the Finnhub client library to fetch quarterly pretax income estimates for a specific company symbol.

```python
import finnhub
finnhub_client = finnhub.Client(api_key="")

print(finnhub_client.company_pretax_income_estimates('TSLA', freq='quarterly'))
```
Tokens:
Raw