3 Ways to Access Hong Kong Data: SQL, Downloads, and AI Agents

Renavon datasets can be accessed in three different ways, depending on how you work. You don't need to choose one — all three are included with every subscription. Here's how each one works.

1. SQL queries via the REST API¶

This is the most powerful access method. Every Renavon dataset is queryable via the REST API. You authenticate with your API key and run SQL queries directly.

# Get your API key from renavon.com/connect

# Example: count all race results
curl -X POST https://renavon.com/api/v1/query \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT count(*) FROM hkjc_race_results"}'

# Example: recent races at Happy Valley
curl -X POST https://renavon.com/api/v1/query \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT race_date, race_number, horse_name, finishing_position, odds FROM hkjc_race_results WHERE venue = '\''Happy Valley'\'' AND race_date >= '\''2025-01-01'\'' ORDER BY race_date DESC, race_number, finishing_position LIMIT 20"}'

Python¶

import requests
import pandas as pd

API_KEY = "YOUR_API_KEY"

# Query into a pandas DataFrame
response = requests.post(
    "https://renavon.com/api/v1/query",
    headers={"X-API-KEY": API_KEY},
    json={
        "query": """
            SELECT race_date, horse_name, odds, finishing_position
            FROM hkjc_race_results
            WHERE race_date >= '2025-01-01'
              AND is_winner = true
            ORDER BY race_date DESC
        """
    }
)
payload = response.json()
df = pd.DataFrame(
    payload["data"],
    columns=[c["name"] for c in payload["columns"]],
)
print(df.head(10))

Anywhere else with HTTP¶

Any language or tool that can POST JSON works the same way — your API key in the X-API-KEY header, your SQL in the query field of the body, your data back as JSON. R, Go, JavaScript, Postman, n8n: it's the same five-line snippet everywhere.

Watch the row cap¶

Each call returns at most 10,000 rows. The response always includes a truncated boolean: false means you got everything that matched, true means the API cut your result short. For a pipeline that downstream code depends on, check truncated on every response and paginate with a keyset on your sort key — don't silently feed a model or a dashboard a partial slice. For full-dataset bulk pulls, the CSV download in section 2 is faster and never truncated.

2. Download CSV or Excel¶

If you don't want to write SQL, you can download data directly from any dataset page on renavon.com.

Each dataset page has a Download section where you can:

• Download the full dataset as CSV or Excel
• Download a filtered subset by applying filters first
• Download sample data (first 100 rows) without a subscription

This is useful for one-off analysis in Excel, Google Sheets, or any spreadsheet tool. The files are generated on demand and reflect the latest data.

For larger datasets (millions of rows), the SQL method is faster because you can filter server-side before downloading. But for datasets under a few hundred thousand rows, the direct download works well.

3. AI agents (Claude, Cursor, ChatGPT)¶

The same /api/v1/query endpoint is your AI integration point. You don't need a separate MCP server unless you want one — modern Claude (Desktop, Code, or via the API), Cursor, and ChatGPT can all call HTTP endpoints directly inside a conversation.

The simplest path¶

Paste this into your first message and the agent will use it as a template for the rest of the conversation:

curl -X POST https://renavon.com/api/v1/query \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT count(*) FROM hkjc_races"}'

Then ask in plain English:

• "Show me the top 10 jockeys by win rate this season"
• "Find all companies registered in Hong Kong in the last 30 days"
• "Chart the odds movement for the favourite in the most recent race"

The AI writes the SQL, fires the request, and presents the results.

Native MCP integration¶

If you want a first-class tool registration in Claude Desktop or Cursor, wrap the REST endpoint in a tiny custom MCP server. The full setup is in our AI agents guide — about 30 lines of Python and a JSON config block.

Autonomous agents (Manus, Devin)¶

Autonomous AI agents work the same way. Give the agent your API key and the curl example above; it handles authentication, query construction, and result parsing itself. Works with any agent that can run Python (or equivalent).

Which method should I use?¶

All three methods access the same underlying data, updated at the same frequency. Pick whichever fits your workflow — or use all three for different tasks.

Get started at renavon.com/connect.