Finnhub Python API Client

Common errors

• AttributeError: partially initialized module 'finnhub' has no attribute 'Client' (most likely due to a circular import)

  cause The Python script attempting to import `finnhub` is itself named `finnhub.py`, causing Python to import the local file instead of the installed library.
  fix Rename your Python script file to something unique, like `stock_data_fetcher.py`, to resolve the naming conflict.

• {'error': "You don't have access to this resource."}

  cause Attempting to access a Finnhub API endpoint or data type that is not included in your current subscription plan (e.g., trying to fetch premium data with a free API key).
  fix Verify your Finnhub API key and its associated subscription plan. Consult the Finnhub API documentation to confirm the required subscription tier for the specific endpoint you are trying to use.

• HTTPSConnectionPool(host='api.finnhub.io', port=443): Max retries exceeded with url: /api/v1/...

  cause This error typically indicates network issues, a very aggressive rate limit being hit repeatedly without backoff, or firewall/proxy blocking the outbound connection.
  fix First, check your internet connection. If the issue persists, ensure your API key is valid and you're not exceeding rate limits. If running in a restricted environment, check firewall rules or ensure the `api.finnhub.io` domain is whitelisted.

• {'error': 'The API key is invalid.'}

  cause The API key provided to the `finnhub.Client` is incorrect, expired, or has leading/trailing whitespace.
  fix Double-check your Finnhub API key in your dashboard (`finnhub.io/dashboard`). Ensure there are no extra spaces or characters. If using environment variables, confirm it's loaded correctly.

Warnings

• breaking Version 2.0.0 introduced significant changes, simplifying library usage and making return data more compatible with data analysis libraries like pandas. Code written for version 1.x.x will likely break.
  Fix: Refer to the CHANGELOG on GitHub and update your code to align with the new API patterns for `finnhub.Client` and data access methods. Many return values are now more directly consumable by pandas DataFrames.
• gotcha Naming your Python script 'finnhub.py' will lead to a circular import error: 'AttributeError: partially initialized module 'finnhub' has no attribute 'Client''.
  Fix: Rename your script file to anything other than `finnhub.py` (e.g., `my_finnhub_app.py`) to avoid conflicts with the installed library's module name.
• gotcha Free tier API keys often have strict rate limits (e.g., 60 calls/minute) and may not have access to all resources. Exceeding limits results in '429 Too Many Requests', and attempting to access premium data will return 'You don't have access to this resource.'.
  Fix: Implement exponential backoff and retry logic for API calls to handle rate limits gracefully. For 'access denied' errors, check the Finnhub API documentation to confirm if the requested endpoint requires a premium subscription, or verify your API key and plan details.
• gotcha When deploying applications using `finnhub-python` on certain hosting platforms (e.g., PythonAnywhere), you might encounter '403 Forbidden' errors due to proxy restrictions.
  Fix: Ensure that the Finnhub API domain (`api.finnhub.io`) is whitelisted on your hosting provider. Contact your hosting support if necessary to confirm and enable access.

Install

• pip install finnhub-python Install with pip

Imports

• Client
  wrong:

  from finnhub import Client

  correct:

  import finnhub
  finnhub_client = finnhub.Client(api_key=os.environ.get('FINNHUB_API_KEY', ''))

  The Client class is typically accessed directly as an attribute of the imported 'finnhub' module, not imported directly from the package.

Quickstart

This quickstart demonstrates how to initialize the Finnhub client using an API key from an environment variable and fetch basic stock data such as a real-time quote and company profile for Apple Inc. Make sure to replace 'YOUR_FREE_API_KEY_HERE' with a valid Finnhub API key or set the FINNHUB_API_KEY environment variable.

import finnhub
import os

# Get API key from environment variable for security
finnhub_api_key = os.environ.get('FINNHUB_API_KEY', 'YOUR_FREE_API_KEY_HERE')

# Setup client
finnhub_client = finnhub.Client(api_key=finnhub_api_key)

# Fetch real-time stock quote for Apple Inc.
quote = finnhub_client.quote('AAPL')
print("AAPL Quote:", quote)

# Fetch company profile for Apple Inc.
company_profile = finnhub_client.company_profile2(symbol='AAPL')
print("AAPL Company Profile:", company_profile)