Python Client Guide

Use the popular requests library to interact with the Shorted API. It provides a simple, human-friendly interface for HTTP.

Prerequisites

Python 3.8+
`pip install requests`

Authentication

Include your API key in the Authorization header as a Bearer token. Public endpoints work without authentication but have lower rate limits.

import requests

url = "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
}

response = requests.post(url, json={"limit": 10}, headers=headers)
data = response.json()

Example: Get Top Shorted Stocks

Retrieve the most heavily shorted stocks on the ASX, sorted by short interest percentage.

import requests

url = "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts"
response = requests.post(url, json={"limit": 10, "offset": 0})
data = response.json()

for stock in data["stocks"]:
    print(f"{stock['productCode']}: {stock['currentPercent']}%")

Example: Get Stock Details

Fetch detailed information about a specific stock by its ASX code.

import requests

url = "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetStock"
response = requests.post(url, json={"productCode": "BHP"})
stock = response.json()["stock"]

print(f"{stock['companyName']} ({stock['productCode']})")
print(f"Short position: {stock['currentPercent']}%")
print(f"Industry: {stock['industry']}")

Error Handling

The API returns standard HTTP status codes. Rate limited requests return 429 with a Retry-After header. Always check the response status before parsing the body.

import requests
import time

def api_call(path, body, api_key=None):
    headers = {"Content-Type": "application/json"}
    if api_key:
        headers["Authorization"] = f"Bearer {api_key}"

    response = requests.post(
        f"https://shorts-uiekqxovma-km.a.run.app{path}",
        json=body,
        headers=headers,
    )

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        print(f"Rate limited. Retrying in {retry_after}s...")
        time.sleep(retry_after)
        return api_call(path, body, api_key)

    response.raise_for_status()
    return response.json()

# Usage
data = api_call(
    "/shorts.v1alpha1.ShortedStocksService/GetTopShorts",
    {"limit": 10},
    api_key="YOUR_API_KEY",
)

All Endpoints

See the full API reference for all available endpoints, request/response schemas, and the interactive "Try It" panel.