Cliente Python API

El Cliente Python de Quantdle es una librería fácil de usar que simplifica la descarga de datos desde Quantdle. Este cliente se ocupa de toda la complejidad de descarga, extracción y procesamiento de datos, proporcionándote DataFrames de pandas o polars limpios y listos para usar.

¿Por qué usar el Cliente Python?

Acceso Simple a Datos

Descarga datos históricos de mercado con solo unas pocas líneas de código.

Alto Rendimiento

Descargas paralelas y chunking inteligente para descargas más rápidas.

Múltiples Formatos

Soporte para DataFrames tanto de pandas como de polars.

Configuración Cero

Funciona desde el primer momento con configuración mínima.

Instalación

Instala el cliente Python de Quantdle usando pip:

Instalación Estándar

pip install quantdle

Con Soporte Polars

pip install quantdle[polars]

Requisitos de Versión de Python

El cliente Python de Quantdle requiere Python 3.9 o superior. Asegúrate de que tu versión de Python sea compatible antes de instalar.

Puedes comprobarlo en la página del proyecto de pypi.org/project/quantdle/.

Obtener tus Credenciales API

Antes de usar el cliente Python, necesitarás obtener tus credenciales API desde el panel de Quantdle.

1. Inicia sesión en tu cuenta de Quantdle
2. Navega a la sección API Keys en tu panel
3. Haz clic en “Generate API Keys” para crear tus credenciales
4. Copia tanto tu API Key como tu API Key ID - necesitarás ambos para la autenticación

¿Necesitas ayuda con las API Keys?

Para instrucciones detalladas sobre generar claves API, consulta nuestra guía de API Keys.

Inicio Rápido

Así es como puedes empezar con el cliente Python de Quantdle en solo unas pocas líneas de código:

import quantdle as qdl

# Inicializa el cliente con tus credenciales API
client = qdl.Client(
    api_key="tu-api-key",
    api_key_id="tu-api-key-id"
)

# Descarga datos para EURUSD
df = client.download_data(
    symbol="EURUSD",
    timeframe="H1",
    start_date="2023-01-01",
    end_date="2023-12-31"
)

# Muestra las primeras filas
print(df.head())

Formato de Datos

Por defecto, el cliente devuelve datos como un DataFrame de pandas. También puedes solicitar DataFrames de polars configurando output_format="polars" en el método download_data().

Ejemplos de Uso Básico

Descargar Diferentes Símbolos y Marcos Temporales

import quantdle as qdl

# Inicializa el cliente una vez
client = qdl.Client(
    api_key="tu-api-key",
    api_key_id="tu-api-key-id"
)

# Descarga diferentes símbolos y marcos temporales
xau_data = client.download_data("XAUUSD", "D1", "2023-01-01", "2023-12-31")
eur_data = client.download_data("EURUSD", "H1", "2023-01-01", "2023-01-31")

Usando DataFrames de Polars

Para conjuntos de datos grandes, los DataFrames de polars ofrecen mejor rendimiento y eficiencia de memoria:

import quantdle as qdl

client = qdl.Client(
    api_key="tu-api-key",
    api_key_id="tu-api-key-id"
)

# Obtener datos como DataFrame de polars
df = client.download_data(
    symbol="XAUUSD",
    timeframe="D1",
    start_date="2023-01-01",
    end_date="2023-12-31",
    output_format="polars"
)

print(f"Forma de los datos: {df.shape}")
print(df.head())

Descubrir Símbolos Disponibles

Antes de descargar datos, puedes verificar qué símbolos están disponibles para tu cuenta:

import quantdle as qdl

client = qdl.Client(
    api_key="tu-api-key",
    api_key_id="tu-api-key-id"
)

# Obtener todos los símbolos disponibles para tu cuenta
symbols = client.get_available_symbols()
print(f"Símbolos disponibles: {symbols}")

# Obtener información sobre un símbolo específico
info = client.get_symbol_info("EURUSD")
print(f"EURUSD disponible desde {info['available_from']} hasta {info['available_to']}")

Características Avanzadas

Manejo de Rangos de Fechas Grandes

El cliente maneja automáticamente rangos de fechas grandes dividiéndolos en chunks más pequeños para evitar timeouts:

import quantdle as qdl

client = qdl.Client(
    api_key="tu-api-key",
    api_key_id="tu-api-key-id"
)

# Descarga 10 años de datos - será automáticamente dividido en chunks
df = client.download_data(
    symbol="EURUSD",
    timeframe="H1",
    start_date="2014-01-01",
    end_date="2023-12-31",
    chunk_size_years=5  # Descargar en chunks de 5 años
)

Optimización de Rendimiento

Personaliza el comportamiento de descarga para un rendimiento óptimo:

import quantdle as qdl

client = qdl.Client(
    api_key="tu-api-key",
    api_key_id="tu-api-key-id"
)

# Personalizar comportamiento de descarga
df = client.download_data(
    symbol="EURUSD",
    timeframe="M5",
    start_date="2023-01-01",
    end_date="2023-12-31",
    max_workers=8,           # Aumentar descargas paralelas
    show_progress=True,      # Mostrar barras de progreso
    chunk_size_years=3       # Chunks más pequeños para actualizaciones más frecuentes
)

Consejos de Rendimiento

• Usa descargas paralelas: El parámetro max_workers controla las descargas concurrentes
• Elige tamaños de chunk apropiados: Chunks más grandes significan menos llamadas API pero tiempos de espera más largos
• Cachea datos descargados: Guarda DataFrames localmente para evitar re-descargas
• Usa polars para conjuntos de datos grandes: Más eficiente en memoria para datasets >1GB

Marcos Temporales Disponibles

La API de Quantdle soporta los siguientes marcos temporales:

Marco Temporal	Descripción
M1	1 minuto
M5	5 minutos
M15	15 minutos
M30	30 minutos
H1	1 hora
H4	4 horas
D1	1 día

Selección de Marco Temporal

Elige tu marco temporal basado en tus necesidades de análisis. Datos de mayor frecuencia (M1, M5) proporcionan análisis más granular pero conjuntos de datos más grandes, mientras que datos diarios (D1) son adecuados para análisis a largo plazo.

Estructura del DataFrame

El DataFrame devuelto contiene las siguientes columnas:

Columna	Tipo	Descripción
timestamp	datetime	Timestamp de la barra
open	float	Precio de apertura
high	float	Precio máximo
low	float	Precio mínimo
close	float	Precio de cierre
tickvol	int	Volumen de ticks (número de nuevos ticks)
volume	int	Volumen de trading
spread	int	Spread promedio de la barra
spreadmax	int	Spread máximo de la barra
spread_open	int	Spread de apertura de la barra

Características de los datos de spread

Todos los datos de spread se capturan en resolución de tick. Por lo tanto, la columna spread es el spread promedio de todos los ticks en la barra, la columna spreadmax es el spread máximo de esos ticks, y la columna spread_open es el spread presente en el primer tick de la barra.

Ejemplo de Salida del DataFrame

# Estructura de ejemplo de salida
                    timestamp     open     high      low    close  tickvol     volume  spread  spreadmax  spreadopen
0  2023-06-30 15:34:00         1.08840  1.08867  1.08829  1.08861      389  369332000       4          7           2
1  2023-06-30 15:35:00         1.08862  1.08874  1.08849  1.08854      302  318511000       4          7           4
2  2023-06-30 15:36:00         1.08859  1.08880  1.08844  1.08851      281  339198000       3          7           1
3  2023-06-30 15:37:00         1.08851  1.08898  1.08849  1.08881      253  328819000       3          6           3
...

Gestión de Errores

El cliente incluye una gestión robusta de errores para escenarios comunes:

import quantdle as qdl

client = qdl.Client(
    api_key="tu-api-key",
    api_key_id="tu-api-key-id"
)

try:
    df = client.download_data(
        symbol="SIMBOLO_INVALIDO",
        timeframe="H1",
        start_date="2023-01-01",
        end_date="2023-12-31"
    )
except ValueError as e:
    print(f"Parámetro inválido: {e}")
except ConnectionError as e:
    print(f"Error de red: {e}")
except Exception as e:
    print(f"Error inesperado: {e}")

Escenarios de Error Comunes

• Símbolo inválido: Verifica símbolos disponibles usando get_available_symbols().
• Problemas de rango de fechas: Asegúrate de que start_date sea anterior a end_date y dentro del rango de datos disponibles.
• Timeouts de red: El cliente reintenta automáticamente, pero verifica tu conexión a internet.
• Límites de tasa de API: El cliente gestiona el chunking, pero debes ser consciente de no hacer muchas solicitudes concurrentes.

Mejores Prácticas

1. Reutilizar Instancias del Cliente

Crea el cliente una vez y reutilízalo para múltiples descargas:

# Bueno: Crear cliente una vez
client = qdl.Client(api_key="...", api_key_id="...")

# Descargar múltiples conjuntos de datos
eurusd = client.download_data("EURUSD", "H1", "2023-01-01", "2023-12-31")
gbpusd = client.download_data("GBPUSD", "H1", "2023-01-01", "2023-12-31")

# Malo: Crear nuevo cliente para cada descarga
# Esto es ineficiente y puede alcanzar límites de tasa

2. Cachear Datos Descargados

Guarda conjuntos de datos grandes localmente para evitar re-descargas:

import quantdle as qdl
import pandas as pd

client = qdl.Client(api_key="...", api_key_id="...")

# Descargar y guardar en archivo
df = client.download_data("EURUSD", "H1", "2023-01-01", "2023-12-31")
df.to_parquet("eurusd_h1_2023.parquet")  # Formato binario eficiente

# Más tarde, cargar desde archivo en lugar de re-descargar
df = pd.read_parquet("eurusd_h1_2023.parquet")

3. Usar Rangos de Fechas Apropiados

Sé consciente del rango de datos que estás solicitando:

# Bueno: Rango de fechas razonable
df = client.download_data("EURUSD", "H1", "2023-01-01", "2023-12-31")

# Considera cuidadosamente: Rango muy grande
df = client.download_data("EURUSD", "M1", "2020-01-01", "2023-12-31")  # ¡4 años de datos por minuto!

Límites de Tasa de API

Consideraciones de Límite de Tasa

Quantdle tiene límites de tasa de API para asegurar un uso justo. El cliente Python automáticamente:

• Divide solicitudes grandes para evitar timeouts
• Implementa lógica de reintento para fallos temporales
• Espacía solicitudes para prevenir sobrecargar la API

Sin embargo, aún debes ser consciente de hacer muchas solicitudes concurrentes.

Solución de Problemas

Problemas Comunes y Soluciones

Errores de Autenticación

• Verifica que tu API Key y API Key ID sean correctos
• Asegúrate de que tu cuenta tenga una suscripción activa
• Verifica que tus claves API no hayan expirado

Timeouts de Descarga

• Intenta reducir el parámetro chunk_size_years
• Verifica la estabilidad de tu conexión a internet
• Verifica que el rango de fechas solicitado tenga datos disponibles

Problemas de Memoria con Conjuntos de Datos Grandes

• Usa output_format="polars" para mejor eficiencia de memoria
• Descarga rangos de fechas más pequeños y combínalos localmente
• Considera usar procesamiento en streaming para conjuntos de datos muy grandes

Símbolo No Encontrado

• Usa get_available_symbols() para verificar símbolos disponibles
• Verifica el formato del nombre del símbolo (ej. “EURUSD” no “EUR/USD”)

Obtener Ayuda

Si encuentras problemas con el cliente Python:

1. Verifica el mensaje de error - la mayoría de errores incluyen detalles útiles sobre qué salió mal.
2. Revisa los ejemplos en esta documentación para asegurar el uso correcto.
3. Visita nuestra página de FAQs para ayuda adicional.
4. Reporta bugs en nuestro repositorio de GitHub.

Recursos de Soporte

• GitHub Issues: Para bugs y solicitudes de características
• Documentación: Esta guía y referencia de API
• Soporte de Quantdle: Para preguntas de cuenta y suscripción
• Página PyPI: Última versión y notas de lanzamiento en pypi.org/project/quantdle/

¿Qué más puedes hacer?

Ahora que sabes cómo usar el cliente Python, explora estos temas relacionados:

• Información de Símbolos - Aprende sobre los instrumentos de trading disponibles.
• Símbolos Personalizados - Usando símbolos personalizados en MetaTrader 5.
• Gestión de API Keys - Gestionando tus credenciales API.

Referencia de Símbolos

Explora todos los símbolos disponibles y sus especificaciones

Ver Símbolos →

Integración MetaTrader

Usa el Expert Advisor para integración directa con MT5

Instalar EA →