# Python
URL: /docs/examples/python.mdx

Integre a API brapi.dev em suas aplicações Python usando a biblioteca requests. Exemplos práticos para buscar cotações de ações da B3.

***

title: 'Python'
description: >-
Integre a API brapi.dev em suas aplicações Python usando a biblioteca
requests. Exemplos práticos para buscar cotações de ações da B3.
full: false
keywords: brapi, api, python, requests, cotações, B3
openGraph:
title: Integração Python - brapi.dev
description: Exemplos de integração usando Python e requests
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
-----------

Integre a API brapi.dev em suas aplicações Python usando nossa SDK oficial ou biblioteca requests.

## 🎉 SDK Oficial Disponível!

A brapi.dev agora oferece uma **SDK oficial Python 3.8+** que facilita muito a integração:

```bash
pip install brapi
```

**Vantagens da SDK:**

* ✅ Type hints completos
* ✅ Suporte síncrono e assíncrono
* ✅ Tratamento de erros automático
* ✅ Retry inteligente
* ✅ Integração com asyncio e aiohttp

**Exemplo rápido:**

```python
from brapi import Brapi

client = Brapi(api_key="seu_token")
quote = client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
```

📚 **[Ver documentação completa da SDK](/docs/sdks/python)**

***

## Integração Manual (Sem SDK)

Se preferir usar requests diretamente, veja os exemplos abaixo.

## Por Que Python para Análise Financeira?

```python
import requests

token = 'SEU_TOKEN'
ticker = 'PETR4'
url = f'https://brapi.dev/api/quote/{ticker}?token={token}'

response = requests.get(url)
data = response.json()

print(data)
```

## Com Tratamento de Erros

```python
import requests
from typing import Dict, Optional

def get_quote(ticker: str, token: str) -> Optional[Dict]:
    """
    Busca cotação de um ativo na B3
    
    Args:
        ticker: Código do ativo (ex: 'PETR4')
        token: Token da API brapi.dev
        
    Returns:
        Dicionário com dados da cotação ou None em caso de erro
    """
    url = f'https://brapi.dev/api/quote/{ticker}?token={token}'
    
    try:
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Erro ao buscar cotação: {e}')
        return None

# Uso
token = 'SEU_TOKEN'
data = get_quote('PETR4', token)

if data and 'results' in data:
    quote = data['results'][0]
    print(f"{quote['symbol']}: R$ {quote['regularMarketPrice']:.2f}")
    print(f"Variação: {quote['regularMarketChangePercent']:.2f}%")
```

## Múltiplos Tickers

```python
def get_multiple_quotes(tickers: list[str], token: str) -> Optional[Dict]:
    """Busca cotações de múltiplos ativos"""
    tickers_param = ','.join(tickers)
    url = f'https://brapi.dev/api/quote/{tickers_param}?token={token}'
    
    try:
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f'Erro: {e}')
        return None

# Uso
tickers = ['PETR4', 'VALE3', 'ITUB4']
data = get_multiple_quotes(tickers, token)

if data:
    for quote in data['results']:
        print(f"{quote['symbol']}: R$ {quote['regularMarketPrice']:.2f}")
```

## Classe Cliente

```python
import requests
from typing import Dict, List, Optional
from dataclasses import dataclass
from datetime import datetime

@dataclass
class Quote:
    """Representa uma cotação de ativo"""
    symbol: str
    short_name: str
    regular_market_price: float
    regular_market_change: float
    regular_market_change_percent: float
    currency: str
    market_cap: Optional[float] = None
    
    @classmethod
    def from_dict(cls, data: Dict) -> 'Quote':
        return cls(
            symbol=data['symbol'],
            short_name=data['shortName'],
            regular_market_price=data['regularMarketPrice'],
            regular_market_change=data['regularMarketChange'],
            regular_market_change_percent=data['regularMarketChangePercent'],
            currency=data['currency'],
            market_cap=data.get('marketCap')
        )

class BrapiClient:
    """Cliente para a API brapi.dev"""
    
    BASE_URL = 'https://brapi.dev/api'
    
    def __init__(self, token: str):
        self.token = token
        self.session = requests.Session()
        self.session.headers.update({
            'User-Agent': 'Python BrapiClient/1.0'
        })
    
    def get_quote(self, ticker: str) -> Optional[Quote]:
        """Busca cotação de um ativo"""
        url = f'{self.BASE_URL}/quote/{ticker}'
        params = {'token': self.token}
        
        try:
            response = self.session.get(url, params=params, timeout=10)
            response.raise_for_status()
            data = response.json()
            
            if data.get('results'):
                return Quote.from_dict(data['results'][0])
            return None
        except requests.exceptions.RequestException as e:
            print(f'Erro ao buscar {ticker}: {e}')
            return None
    
    def get_multiple_quotes(self, tickers: List[str]) -> List[Quote]:
        """Busca cotações de múltiplos ativos"""
        tickers_param = ','.join(tickers)
        url = f'{self.BASE_URL}/quote/{tickers_param}'
        params = {'token': self.token}
        
        try:
            response = self.session.get(url, params=params, timeout=10)
            response.raise_for_status()
            data = response.json()
            
            return [Quote.from_dict(item) for item in data.get('results', [])]
        except requests.exceptions.RequestException as e:
            print(f'Erro ao buscar cotações: {e}')
            return []
    
    def __enter__(self):
        return self
    
    def __exit__(self, *args):
        self.session.close()

# Uso
with BrapiClient('SEU_TOKEN') as client:
    # Cotação única
    quote = client.get_quote('PETR4')
    if quote:
        print(f'{quote.symbol}: R$ {quote.regular_market_price:.2f}')
        print(f'Variação: {quote.regular_market_change_percent:.2f}%')
    
    # Múltiplas cotações
    quotes = client.get_multiple_quotes(['PETR4', 'VALE3', 'ITUB4'])
    for quote in quotes:
        print(f'{quote.symbol}: R$ {quote.regular_market_price:.2f}')
```

## Salvando em CSV

```python
import csv
from datetime import datetime

def save_quotes_to_csv(tickers: List[str], token: str, filename: str):
    """Salva cotações em arquivo CSV"""
    with BrapiClient(token) as client:
        quotes = client.get_multiple_quotes(tickers)
        
        if not quotes:
            print('Nenhuma cotação obtida')
            return
        
        with open(filename, 'w', newline='', encoding='utf-8') as csvfile:
            fieldnames = [
                'timestamp', 'symbol', 'short_name', 'price', 
                'change', 'change_percent', 'currency'
            ]
            writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
            writer.writeheader()
            
            timestamp = datetime.now().isoformat()
            for quote in quotes:
                writer.writerow({
                    'timestamp': timestamp,
                    'symbol': quote.symbol,
                    'short_name': quote.short_name,
                    'price': quote.regular_market_price,
                    'change': quote.regular_market_change,
                    'change_percent': quote.regular_market_change_percent,
                    'currency': quote.currency
                })
        
        print(f'Cotações salvas em {filename}')

# Uso
tickers = ['PETR4', 'VALE3', 'ITUB4', 'BBDC4']
save_quotes_to_csv(tickers, 'SEU_TOKEN', 'quotes.csv')
```

## Com Pandas

```python
import pandas as pd

def get_quotes_dataframe(tickers: List[str], token: str) -> pd.DataFrame:
    """Retorna cotações como DataFrame do pandas"""
    with BrapiClient(token) as client:
        quotes = client.get_multiple_quotes(tickers)
        
        if not quotes:
            return pd.DataFrame()
        
        data = [{
            'symbol': q.symbol,
            'name': q.short_name,
            'price': q.regular_market_price,
            'change': q.regular_market_change,
            'change_percent': q.regular_market_change_percent,
            'currency': q.currency,
            'market_cap': q.market_cap
        } for q in quotes]
        
        return pd.DataFrame(data)

# Uso
df = get_quotes_dataframe(['PETR4', 'VALE3', 'ITUB4'], 'SEU_TOKEN')
print(df)

# Salvar em Excel
df.to_excel('quotes.xlsx', index=False)
```

## Aplicação Flask

```python
from flask import Flask, jsonify
import os

app = Flask(__name__)
BRAPI_TOKEN = os.environ.get('BRAPI_TOKEN')

@app.route('/api/quote/<ticker>')
def get_quote_api(ticker):
    """Endpoint para buscar cotação"""
    with BrapiClient(BRAPI_TOKEN) as client:
        quote = client.get_quote(ticker)
        
        if not quote:
            return jsonify({'error': 'Quote not found'}), 404
        
        return jsonify({
            'symbol': quote.symbol,
            'name': quote.short_name,
            'price': quote.regular_market_price,
            'change_percent': quote.regular_market_change_percent
        })

if __name__ == '__main__':
    app.run(debug=True)
```

## Boas Práticas

1. **Use variáveis de ambiente** para o token
2. **Implemente timeout** nas requisições
3. **Trate erros** adequadamente
4. **Use sessões** para melhor performance
5. **Feche conexões** quando não precisar mais

## Variáveis de Ambiente

```python
import os
from dotenv import load_dotenv

load_dotenv()  # Carrega .env

token = os.environ.get('BRAPI_TOKEN')
if not token:
    raise ValueError('BRAPI_TOKEN não configurado')
```

Arquivo `.env`:

```
BRAPI_TOKEN=seu_token_aqui
```

## Próximos Passos

* Explore [outros exemplos](/docs/examples)
* Veja a [documentação completa](/docs)
* Confira os [endpoints disponíveis](/docs/acoes)