NZXplorer API

Free API access to New Zealand capital market data. Companies, directors, governance scores, stock prices, and 64,000+ market announcements.

Quick Start

Get an API key

Email api@nzxplorer.co.nz with your use case

Add your API key

Include as X-API-Key header

Start building

All endpoints return JSON

curl -H "X-API-Key: YOUR_KEY" \
  "https://nzxplorer.co.nz/api/v1/companies?sector=Technology"

Authentication

All API requests require authentication via an API key. Pass your key in one of two ways:

Header (recommended)

X-API-Key: YOUR_KEY

Query parameter

?api_key=YOUR_KEY

Keep your API key secret. Never expose it in client-side code or public repositories.

Rate Limits

Tier	Rate Limit	Price	Use Case
Free	10 req/min	$0	Personal projects, research, prototyping
Pro	100 req/min	$29/mo	Apps, dashboards, data pipelines
Corporate	500+ req/min	Book a Demo	Teams, commercial use, custom SLAs

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-API-Tier

Bot Protection

API routes are protected against automated scraping. Requests from known scraper user agents (including AI training bots like GPTBot, CCBot, and others) are blocked with a 403 response. All legitimate access requires an API key.

Note: If your application receives a 403 error, ensure you are passing a valid API key via the X-API-Key header and using a standard user agent string.

LLM-Optimized Format

Add ?format=llm to any endpoint for token-optimized output. This strips null values, empty arrays, and metadata — ideal for feeding into LLMs and AI agents.

Standard format

{
  "data": {
    "ticker": "AIR",
    "name": "Air New Zealand",
    "description": null,
    "website_url": null,
    "directors": []
  },
  "meta": {
    "api_version": "v1",
    "timestamp": "2026-03..."
  }
}

LLM format (?format=llm)

{
  "ticker": "AIR",
  "name": "Air New Zealand"
}

~70% fewer tokens. Same data, no nulls or empty fields.

TOON Token-Optimized Output

Add ?format=toon to any endpoint for maximum token compression. TOON (Token-Optimized Object Notation) encodes arrays of objects as pipe-delimited tabular data — 30-60% fewer tokens than JSON with lossless roundtrip fidelity.

Standard JSON

[
  {"ticker":"AIR","name":"Air NZ","sector":"Industrials"},
  {"ticker":"FPH","name":"Fisher & Paykel","sector":"Healthcare"},
  {"ticker":"MEL","name":"Meridian","sector":"Utilities"}
]

TOON format (?format=toon)

ticker|name|sector
AIR|Air NZ|Industrials
FPH|Fisher & Paykel|Healthcare
MEL|Meridian|Utilities

~50% fewer tokens. Lossless — decode(encode(data)) == data. Nested objects use dot-notation key folding.

Best for:AI agent pipelines, MCP tool results, and Copilot tool calls. The NZXplorer Copilot auto-encodes large array results (>8KB) in TOON format internally, reducing token costs by 30-60%. Response header: X-Format: toon. Content-Type: text/plain.

FDC3 Interoperability

Add ?format=fdc3 to supported endpoints for FINOS FDC3 v2.0 standard context types. Enables interoperability with Bloomberg, Refinitiv, IRESS, and other FDC3-compliant desktop applications. All 131 issuers have ISINs, and LEIs are available for 65/131 issuers (50% coverage) via the GLEIF register.

Standard format

{
  "data": {
    "ticker": "AIR",
    "name": "Air New Zealand",
    "isin": "NZAIRE0001S2",
    "sector": "Industrials"
  }
}

FDC3 format (?format=fdc3)

{
  "type": "fdc3.instrument",
  "name": "Air New Zealand",
  "id": {
    "ticker": "AIR",
    "ISIN": "NZAIRE0001S2",
    "LEI": "XN8VX00V0UCRJ3ZGN385"
  },
  "market": {
    "MIC": "XNZE",
    "name": "New Zealand Exchange",
    "COUNTRY_ISOALPHA2": "NZ"
  }
}

Supported endpoints:

/companies/companies/:ticker/directors/directors/:slug/insider-trades/shareholders/:ticker/prices/:ticker/metrics/:ticker/dividends/:ticker/earnings/:ticker

FDC3 context type mapping:

Endpoint	FDC3 Type
/companies	fdc3.instrumentList
/companies/:ticker	fdc3.instrument
/directors	fdc3.contactList
/directors/:slug	fdc3.contact
/insider-trades	fdc3.tradeList
/shareholders/:ticker	fdc3.portfolio
/prices/:ticker	fdc3.chart
/metrics/:ticker	fdc3.valuation
/dividends/:ticker	fdc3.instrument + dividends
/earnings/:ticker	fdc3.instrument + earnings

Desktop Agent Intents

When running inside an FDC3-compliant desktop agent (IRESS MyIress, OpenFin, Glue42), NZXplorer registers intent listeners and broadcasts instrument context automatically. No configuration needed — the integration is a no-op in standard browser environments.

Intent	Context	Action
ViewChart	fdc3.instrument	Navigate to company chart view
ViewInstrument	fdc3.instrument	Navigate to company overview page
ViewProfile	fdc3.contact / fdc3.instrument	Navigate to person or company profile
ViewResearch	fdc3.instrument	Open proxy advisory report
ViewQuote	fdc3.instrument	Return latest price as fdc3.valuation

NZXplorer also broadcasts fdc3.instrument context when users navigate between company pages, enabling other connected apps to update in sync.

App Directory Manifest

NZXplorer publishes an FDC3 App Directory v2 manifest for registration with desktop agent platforms.

View appd.json

Listens For

ViewChartViewInstrumentViewProfileViewResearchViewQuote

Broadcasts

fdc3.instrumentfdc3.instrumentListfdc3.portfolio

Context Listener

fdc3.instrumentfdc3.contactfdc3.organization

NZXplorer Copilot

An AI research assistant that uses all NZXplorer API endpoints to answer natural language questions about NZX-listed companies. Powered by Claude with tool-calling against 36 internal data tools. Features hybrid semantic search with reranking, structured copilot cards for rich visual output, and TOON token optimization for 30-60% cost reduction.

Web Interface

Try the Copilot in your browser — available on every page via the floating button, or as a full-page experience.

Open NZXplorer Copilot →

CLI Agent

A terminal-based research agent with 53 NZX tools, DCF valuation skills, and live RBNZ OCR data. Built on LangChain.

npx nzxplorer-agent

View on GitHub →

API Endpoint

Use the POST /api/v1/ask endpoint to integrate the Copilot into your own applications. Supports SSE streaming, multi-turn conversations, 20 personas across 4 categories: analyst modes (general, macro, governance, risk), investor frameworks (buffett, graham, lynch, etc.), NZ-specific (nz_income, nz_governance), and professional ICPs (retail_investor, financial_adviser, fund_manager, journalist, corporate_secretary, regulator), and session memory. Pass "persona": "fund_manager" to frame analysis through a specific lens. Pass "session_id": "uuid" to continue a prior conversation — the Copilot will inject your watchlist, theses, and prior topics into its context. The SSE done event returns a session_id you can use in subsequent requests. Manage sessions via GET /api/v1/ask/sessions (list) and DELETE /api/v1/ask/sessions?id=X (archive). The Copilot also builds persistent memory across sessions — it remembers your past questions and findings. Manage memories via GET /api/v1/ask/memories (list) and DELETE /api/v1/ask/memories?id=X (delete) or DELETE /api/v1/ask/memories?all=true (clear all).

# Default (general) persona
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the governance score for Air NZ?"}' \
  "https://nzxplorer.co.nz/api/v1/ask"

# With persona (20 available: macro, governance, risk, buffett, fund_manager, journalist, etc.)
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "How does the OCR cycle affect utilities?", "persona": "macro"}' \
  "https://nzxplorer.co.nz/api/v1/ask"

# Resume a prior conversation (session memory)
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What changed since we last discussed?", "session_id": "SESSION_UUID"}' \
  "https://nzxplorer.co.nz/api/v1/ask"

# List your sessions
curl -H "X-API-Key: YOUR_KEY" \
  "https://nzxplorer.co.nz/api/v1/ask/sessions"

Structured Copilot Cards

When analysis fits a known schema, the Copilot returns structured JSON that the UI renders as visual cards. 5 card types are supported:

company_analysis

Bull/bear case, key metrics, governance flags

sector_comparison

Side-by-side multi-company metrics

risk_assessment

Risk level, factors, mitigation, confidence

dividend_outlook

Yield, safety, cut probability, payout ratio

director_profile

Boards, overboarding risk, voting support

Hybrid Search + Reranking

The Copilot's search_semantic tool combines BM25 keyword search with pgvector semantic similarity via Reciprocal Rank Fusion (RRF, k=60), optionally reranked by Cohere rerank-v3.5. This finds both exact keyword matches and conceptual matches across 64,000+ NZX announcements. The same hybrid search powers the /api/v1/semantic-search?mode=hybrid&rerank=true endpoint.

MCP Server

Connect NZXplorer data directly to Claude Desktop, Cursor, or any MCP-compatible client. 172 tools wrapping the full API — including proxy advisory, anomaly detection, market signals, stock screening, accounting quality, IR quality, peer mentions, board briefings, skills matrices, and research briefings.

npx nzxplorer-mcp

Add to your Claude Desktop config or Cursor MCP settings. See GitHub repo for setup instructions.

Multi-MCP Copilot Integration

The NZXplorer Copilot uses a Multi-MCP architecture — it can connect to external MCP servers alongside its native 172 tools. This allows the AI to cross-reference NZXplorer data with live external sources in a single conversation.

NZ Companies Office

Live NZBN lookups, official director lists, registration status — cross-referenced with NZXplorer's extracted data.

Web Search

Real-time news, FMA notices, and breaking company events not yet in the NZXplorer database.

Web Fetch

Read any URL — annual reports, regulatory notices, competitor filings — and combine with NZXplorer analysis.

Check connection status: GET /api/v1/mcp/status

Endpoints

Data Coverage

Dataset	Records	Updated
NZX-listed companies	131	Real-time
Company directors	2,282	Weekly
Governance scores (GRS v2)	131	Monthly
Stock prices (daily OHLCV)	162,000+	Daily
Market announcements	64,442	Daily
Director share transactions	9,453	Weekly
Executive compensation	1,051	Annually
Earnings results	1,079	Annually
Dividends	1,184	Weekly
AGM resolutions	1,941	Annually
Capital raises	11,088	Annually

Error Specification

Code	Error Type	Description	Retry?
`200`	Success	Request succeeded. Data in response body.	N/A
`400`	VALIDATION_ERROR	Invalid parameters, missing required fields, or malformed input.	No — fix request
`401`	UNAUTHORIZED	Missing, invalid, or expired API key.	No — check key
`403`	FORBIDDEN	Valid key but insufficient tier for this endpoint or data scope.	No — upgrade tier
`404`	NOT_FOUND	Ticker, slug, or resource does not exist.	No
`429`	RATE_LIMITED	Rate limit exceeded. Check Retry-After header.	Yes — after Retry-After seconds
`500`	INTERNAL_ERROR	Server error. Logged and alerted automatically.	Yes — with exponential backoff
`502`	EXTERNAL_SERVICE_ERROR	Upstream dependency (Supabase, Anthropic) temporarily unavailable.	Yes — after 5s

Structured Error Response

All error responses follow a consistent JSON envelope with machine-readable error codes, timestamps, and optional validation details. Use the code field for programmatic error handling.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid ticker format. Expected 2-5 uppercase letters.",
    "timestamp": "2026-03-26T02:15:00.000Z",
    "details": [
      {
        "field": "ticker",
        "message": "Must be 2-5 uppercase letters",
        "received": "air new zealand"
      }
    ]
  }
}

Institutional SLAs & Uptime

Uptime guarantees with SLA credits for Corporate plans. Real-time status at /status. Health check: GET /api/v1/health.

Tier	Uptime SLA	Max Downtime/Month	SLA Credits
Free	99.0%	7h 18m	None
Pro	99.5%	3h 39m	None
Corporate	99.9%+	43m 50s	Negotiated per agreement

API Response Time Targets (p95)

Request Type	Target (p95)	Examples
Simple lookup	< 200ms	/companies/{ticker}, /governance-scores/{ticker}
List/search query	< 500ms	/companies, /directors, /insider-trades
Complex analytics	< 2s	/screener, /semantic-search, /fair-value/{ticker}
PDF generation	< 5s	/proxy/{ticker} (PDF export)
XLSX export	< 10s	/export/xlsx
AI-powered (Copilot)	< 30s	/ask, /deep-research/{ticker}

Incident Response

Severity	Definition	Response	Resolution
P1 — Critical	API fully unavailable or data loss	15 min	4 hours
P2 — Major	Degraded performance (>2x latency) or partial outage	1 hour	8 hours
P3 — Minor	Single endpoint error or stale data	4 hours	48 hours
P4 — Low	Documentation issue or cosmetic bug	1 business day	Next release

Observability Headers

Every API response includes correlation and performance headers for debugging and monitoring.

Header	Description
X-Request-Id	UUID correlation ID (propagated or generated per request)
X-Response-Time	Server-side processing time in milliseconds
X-RateLimit-Limit	Max requests per minute for your tier
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when window resets
X-API-Tier	Your API tier (free/pro/enterprise/institutional)
X-Format	Response format (json/llm/toon/fdc3)

Scheduled Maintenance

Window: Sundays 00:00-06:00 NZST. 48-hour advance notice via email to all API key holders. Automated maintenance (database optimizations, index rebuilds) runs without downtime. Unscheduled emergency maintenance may occur with best-effort notification.

Data Freshness SLAs

Documented update cadence for every data table. Freshness is monitored by automated audit scripts and stored in data_freshness_alerts. View current freshness at /status.

Data / Endpoint	Freshness SLA	Update Schedule	Source
Stock prices (OHLCV)	< 1 trading day	Daily 6:00 UTC (+ hourly intraday)	Yahoo Finance
Performance metrics	< 1 trading day	Daily 6:00 UTC (step 3)	Derived from prices
Technical signals (RSI, SMA)	< 1 trading day	Daily 6:00 UTC (step 4)	Derived from prices
Market announcements	< 4 hours	Hourly 21:00-04:00 UTC (trading hours)	NZX API
Announcement sentiment	< 1 day	Daily 5:00 UTC	Claude Haiku AI
Insider trades	< 7 days	Weekly Saturday 6:00 UTC	NZX SHINTR PDFs
GRS governance scores	< 7 days	Weekly Monday 7:00 UTC	Computed from 6 components
Accounting quality scores	< 30 days	Monthly 1st 8:00 UTC	M-score, F-score, Z-score
Director appointments	< 7 days	Weekly Wednesday 8:00 UTC	MBIE Companies Office
AGM calendar & results	< 7 days	Weekly Wednesday 6:00 UTC	NZX announcements
Annual reports (financials)	< 7 days of filing	Weekly Sunday 8:00 UTC	NZX PDFs + Claude Haiku
Earnings results	< 2 days of FLLYR/HALFYR	Triggered by announcement	NZX announcements
Financial statements	< 14 days of annual report	Extracted on report discovery	Annual report PDFs
Dividends	< 1 day	Daily with announcements	NZX DVDEND announcements
Fund holdings (ETF)	< 30 days	Monthly 5th 20:00 UTC	ETF factsheets + Disclose
Broker/analyst consensus	< 7 days	Weekly Saturday 7:00 UTC	Yahoo Finance
Director skills & bios	< 30 days	Monthly 1st 10:00 UTC	Annual report PDFs
Executive compensation	< 30 days	Monthly 8th 7:00 UTC	Annual report PDFs
Corporate buzzwords	< 30 days	Monthly 15th 6:00 UTC	Regex scan of announcements
Political connections	< 90 days	Quarterly	Parliament.nz, Electoral Commission
Insolvency screening	< 7 days	Weekly Friday 7:00 UTC	MBIE Insolvency Register
Court litigation	< 30 days	Monthly 1st 7:00 UTC	Ministry of Justice API
Cross-platform links	< 30 days	Monthly 1st 7:00 UTC	Bio NER extraction
Signal fusions	< 1 day	Daily 17:30 UTC	10-rule composite detection

Monitoring: Automated audit-data-freshness.cjs runs daily at 18:00 UTC checking 8 core data types against thresholds. Weekly audits run data quality (10 integrity checks), completeness (12 categories per company), and random sampling (~65 records). Results stored in data_freshness_alerts, data_quality_issues, data_completeness_scores tables. Institutional clients receive email alerts for any SLA breach.

NZXplorer API v1 — New Zealand Capital Market Intelligence

Questions? Email api@nzxplorer.co.nz

NZXplorer API Documentation

Loading developer portal...