# NZXplorer

> NZXplorer is a New Zealand financial intelligence API covering 131 NZX-listed companies with 110+ REST endpoints, 131 AI Copilot tools, 131 MCP tools, and 51 screener presets. 266-column screener. Data includes financials, governance scores, director intelligence, insider trades, proxy advisory, ESG, ownership, macro, board recruitment, and cross-platform company directorships (48K+ records).

## API Base URL

https://nzxplorer.co.nz/api/v1

## Authentication

API Key via `X-API-Key` header or `?api_key=` query parameter. Get a key at https://nzxplorer.co.nz/account

## Tiers

- Free: 10 req/min, 3 alert subscriptions
- Pro ($29/mo): 60 req/min, 20 alerts
- Enterprise ($199/mo): 300 req/min, 100 alerts, webhooks, bulk data
- Institutional ($1,250/mo): Custom limits, white-label, SLA

## Endpoints

### Company Data
- GET /companies — List all NZX companies (?include=directors,financials,governance,price)
- GET /companies/{ticker} — Company detail with includes
- GET /governance — All Governance Risk Scores (GRS)

### Financial Data
- GET /financials/{ticker} — Income statements, balance sheets, cash flow, ratios (?statement=income|balance|cash_flow|metrics&year=2020-2025)
- GET /financials/{ticker}/xbrl — IFRS-tagged financial statements (54 taxonomy concepts)
- GET /earnings/{ticker} — Structured earnings results with themes and management tone
- GET /earnings-themes/{ticker} — AI-extracted themes, tone, forward-looking statements
- GET /narrative-tracker/{ticker} — YoY messaging evolution with tone shifts
- GET /dividends/{ticker} — Dividend history with safety scores, cut probability
- GET /metrics — All company financial metrics
- GET /metrics/{ticker} — Detailed metrics with live valuation
- GET /annual-reports/{ticker} — Report URLs with extraction status (2,032 reports)
- GET /segments/{ticker} — Revenue segments by business line/geography

### People & Governance
- GET /directors — All directors
- GET /directors/{slug} — Director detail (?include=trades,remuneration,exec_comp)
- GET /director-report/{slug} — Full due diligence report (JSON)
- GET /director-report/{slug}/pdf — PDF report
- GET /board-report/{ticker} — Board composition analytics (JSON)
- GET /board-report/{ticker}/pdf — Board composition report (PDF)
- GET /executive-compensation/{ticker} — CEO and executive pay data
- GET /board-changes/{ticker} — Board appointment/resignation history
- GET /skills-matrix/{ticker} — Board skills matrix with gap analysis (12 IoD NZ categories)
- GET /board-gap-report/{ticker} — Board Gap Intelligence Report
- GET /board-gap-report/{ticker}/pdf — Print-optimized board gap report
- GET /board-vacancies — Current board vacancies (Appoint Better Boards + IoD NZ)

### Market Data
- GET /prices/{ticker} — Historical stock prices (daily OHLCV)
- GET /insider-trades — Director share transactions with conviction scoring
- GET /announcements — NZX announcements (64K+ indexed)
- GET /signals — Unified market signals (11 types)
- GET /anomalies — Anomaly detection (16 algorithms, 7 categories)
- GET /takeovers/{ticker} — M&A and takeover data
- GET /capital-raises/{ticker} — Capital raise archive
- GET /capital-raise-sentiment/{ticker} — Capital raise context: strength/neutral/desperation classification with post-raise return tracking
- GET /credit-ratings/{ticker} — Credit rating history

### Ownership Intelligence
- GET /shareholders/{ticker} — Top 20 shareholders with holder type classification
- GET /substantial-holders/{ticker}/notices — Substantial holder notice history
- GET /beneficial-ownership/{ticker} — Reconstructed beneficial ownership (fund-level)
- GET /kiwisaver-holdings/{ticker} — KiwiSaver fund exposure

### Proxy Advisory & Research
- GET /proxy-report/{ticker} — AI proxy voting recommendations (JSON)
- GET /proxy-report/{ticker}/pdf — Proxy report PDF
- GET /board-briefing/{ticker} — Board meeting prep briefing (9 data sources)
- GET /board-briefing/{ticker}/pdf — Board briefing PDF
- GET /research/{ticker} — AI investment research briefing (4 templates: board_meeting, investment_thesis, due_diligence, general)
- GET /deep-research/{ticker} — Deep equity research (35+ proprietary sources, 5 analysis phases)
- POST /deep-research/{ticker} — Stream deep research via SSE
- GET /broker-coverage/{ticker} — Analyst consensus, ratings, forecasts (?include=ratings,forecasts,reports,summary)

### Search
- GET /semantic-search — Hybrid keyword + semantic + reranked search (64K announcements)
- GET /keyword-trends — Keyword frequency trends across announcements
- GET /risk-language/{ticker} — Risk language scoring from annual reports

### Screener
- GET /screener — 266-column screener with 51 presets (?preset=value|growth|quality|dividend_aristocrats|rate_sensitive|property_reits|insider_buying|...)

### ESG & Corporate
- GET /esg/{ticker} — ESG metrics and scores
- GET /esg/{ticker}/xbrl — NZ Climate Standards ESG disclosure
- GET /audit-changes — Auditor change history
- GET /accounting-quality/{ticker} — Accounting quality scores (M-score, F-score, Z-score)
- GET /ir-quality/{ticker} — Investor Relations quality score (0-100)

### Intelligence
- GET /peer-mentions/{ticker} — Peer mention network with 10 relation types
- GET /political-connections/{ticker} — MP interests + party donations linked to NZX
- GET /management-credibility/{ticker} — Management credibility score (0-100)
- GET /macro-regime — Current NZ macro regime (OCR, GDP, CPI, FX)
- GET /macro-exposure/{ticker} — Company-specific macro sensitivity
- GET /macro-history — Historical macro indicators
- GET /property-portfolio/{ticker} — Property asset details for REITs

### Alerts & Webhooks
- GET /alerts/subscriptions — List alert subscriptions
- POST /alerts/subscriptions — Create alert (11 signal types, 7 anomaly categories)
- GET/PATCH/DELETE /alerts/subscriptions/{id} — Manage subscription
- GET /webhooks — List webhooks (Enterprise)
- POST /webhooks — Create webhook with filters
- GET/PUT/DELETE /webhooks/{id} — Manage webhook
- GET /webhooks/{id}/history — Delivery history
- POST /webhooks/{id}/test — Test payload delivery
- GET /announcement-alerts — List announcement content-matching alert subscriptions
- POST /announcement-alerts — Create announcement alert (keyword/type/ticker/sector filters)
- GET/PUT/DELETE /announcement-alerts/{id} — Manage announcement alert

### Widgets
- GET /widgets/{type} — Embeddable widgets (7 types: price-card, governance-badge, dividend-history, insider-activity, financials-summary, company-overview, sector-heatmap)
- GET /sector-heatmap — Standalone sector performance data
- GET /alpha-score/{ticker} — Alpha Score composite rating (0-100)
- GET /committee-chairs — Committee chair directory
- GET /corporate-relationships/{ticker} — Related party transactions and material contracts
- POST /director-claims — Director-as-a-Service profile claims

### Institutional / Compliance
- GET /institutional-ownership/{ticker} — KiwiSaver + institutional + top 20 shareholders + beneficial ownership
- GET /vote-history — Cross-fund vote comparison (?ticker=&fund=&year=&dissent_only=true)
- GET /compliance-audit — Audit trail export (?from=&to=&format=json|csv)

### Bulk Data
- GET /downloads/{dataset} — 13 downloadable datasets (?ticker=&year=&sector= filters, Enterprise tier)
- GET /export/xlsx — XLSX export (6 dataset types)

## MCP Server

131 tools available via MCP protocol. Install: `npx nzxplorer-mcp`

Remote server (coming soon): mcp.nzxplorer.co.nz

## AI Copilot

131 tools available at POST /ask (SSE streaming). Natural language queries about any NZX company. 4 analyst personas (general, macro, governance, risk). Session persistence and persistent cross-session memory (Mem0 pattern with pgvector). Manage sessions: GET/DELETE /ask/sessions. Manage memories: GET/DELETE /ask/memories.

## Data Coverage

- 131 NZX-listed companies
- 2,277 directors with skills, qualifications, remuneration
- 3,257 executive records
- 64,442 indexed announcements
- 2,032 annual/interim reports (FY2010-2025)
- 9,453 insider trades
- 8,594 top-20 shareholder records
- 1,079 structured earnings results
- 30+ years stock price history

## Links

- [Full API Reference (llms-full.txt)](https://nzxplorer.co.nz/llms-full.txt) — detailed parameter docs for all endpoints
- [API Documentation](https://nzxplorer.co.nz/developers)
- [Product Docs](https://nzxplorer.co.nz/docs)
- [Pricing](https://nzxplorer.co.nz/pricing)
- [OpenAPI Spec](https://nzxplorer.co.nz/openapi.json)