NZX Data in Google Sheets
9 custom functions including array formulas, 200+ metrics covering financials, governance, ESG, ownership, and intelligence. All 131 NZX-listed companies. One script, no extensions to install.
Set Up in 2 Minutes
No add-on marketplace approval needed. Copy the script directly into your Google Sheet.
Copy the Script
Click the "Copy Script" button below to copy the entire Google Apps Script code to your clipboard.
Open Apps Script
In Google Sheets, go to Extensions > Apps Script. Delete any existing code in Code.gs and paste the NZXplorer script.
Set Your API Key
Save the script (Ctrl+S). Reload your spreadsheet. Click the NZXplorer menu > Set API Key and enter your key.
Use the Functions
Type =NZX_PRICE("FPH") in any cell. The function auto-completes and data appears. Results are cached for 6 hours.
7 Scalar Functions
Each function auto-completes in Google Sheets. Results are cached for 6 hours to stay within Google quotas.
NZX_PRICE
Latest closing stock price in NZD.
=NZX_PRICE("FPH")35.20NZX_GRS
Governance Risk Score (0-100). Higher = better governance.
=NZX_GRS("FPH")82NZX_DSS
Dividend Safety Score (0-100). Payout ratio, FCF coverage, consistency.
=NZX_DSS("MEL")85NZX_ICS
Insider Conviction Score (0-100). Buy/sell ratio, director alignment.
=NZX_ICS("CEN")68NZX_DIVIDEND
Latest dividend per share in NZ cents.
=NZX_DIVIDEND("SPK")12.5NZX_FINANCIALS
Financial data by company, year, and field. Values in NZD thousands.
=NZX_FINANCIALS("FPH", 2024, "revenue")1856000NZXPLORER
Universal function. Fetches any of 200+ metrics: pe_ratio, roe, fair_value_estimate, board_busyness_score, alpha_1y, rsi_14, and more.
=NZXPLORER("AIR", "pe_ratio")18.52 Array Formulas
Return multi-cell results from a single formula. Compare multiple tickers and metrics at once.
NZX_SCREENER
Multi-ticker, multi-metric matrix. Returns a 2D array with header row. Accepts comma-separated strings or cell ranges.
=NZX_SCREENER("FPH,AIR,MEL", "pe_ratio,roe,dividend_yield")NZX_BULK
One metric across many tickers. Returns a column array. Use cell ranges for dynamic ticker lists.
=NZX_BULK(A1:A10, "pe_ratio")Example: Stock Comparison Table
With array formulas, a single formula replaces the entire table. Use =NZX_SCREENER("FPH,AIR,MEL,SPK,CEN", "pe_ratio,dividend_yield,grs_score,dss_score") to generate this comparison in one cell.
| Ticker | P/E Ratio | Yield | GRS | DSS |
|---|---|---|---|---|
| FPH | 28.3 | 1.8% | 82 | 71 |
| AIR | 12.1 | 3.2% | 75 | 68 |
| MEL | 22.5 | 4.1% | 88 | 85 |
| SPK | 15.8 | 5.6% | 72 | 79 |
| CEN | 31.2 | 4.5% | 80 | 82 |
200+ Available Metrics
Pass any of these as the second argument to NZXPLORER(). Example: =NZXPLORER("FPH", "roe")
Valuation
pe_ratiopb_ratiops_ratioev_to_ebitdaev_to_ebitev_to_revenueearnings_yieldfair_value_estimateprice_to_fair_valueProfitability
roeroaroicnet_marginebitda_margingross_margincomprehensive_roeeffective_tax_rateDividends
dividend_yieldpayout_ratiodps_centsdss_scoreimputation_percentdrp_availableLeverage
debt_to_equitycurrent_ratiointerest_covernet_debt_to_ebitdaequity_ratioquick_ratioGrowth
revenue_growthnet_profit_growthebitda_growtheps_growthdps_growthequity_growthPerformance
return_1dreturn_1mreturn_1yreturn_ytdalpha_1yvolatility_1ypct_from_52w_highTechnical
rsi_14sma_50sma_200golden_crossdeath_crossvolume_ratioGovernance
grs_scoregrs_ratingboard_structure_scorenzx_compliance_scoreboard_busyness_scoreboard_independence_pctboard_female_pctRisk & Quality
aq_scorem_scoref_scorez_scoremax_director_failure_rateconflict_risk_scoreaudit_going_concernOwnership
top_holder_pcttop5_holder_pctownership_hhinominee_pctpassive_vs_active_ratiofund_manager_countESG & Property
scope1_emissionstrifremployee_countavg_cap_rateavg_wale_yearsnta_premium_pctclimate_risk_scoreIntelligence
ics_scoreceo_tenure_yearsanalyst_countconsensus_upside_pctguidance_accuracy_avgsentiment_scoremp_interest_countFinancial Statement Fields
Use with NZX_FINANCIALS(ticker, year, field). Values are in NZD thousands.
Income Statement
revenuenet_profitebitdaebitoperating_expensesgross_profitBalance Sheet
total_assetstotal_liabilitiestotal_equitycash_and_equivalentstotal_borrowingsCash Flow
operating_cash_flowinvesting_cash_flowfinancing_cash_flowcapexfree_cash_flowTechnical Details
How the add-on works under the hood.
API-Powered
Calls the NZXplorer REST API (v1) at nzxplorer.co.nz/api/v1/ using UrlFetchApp. Authenticated via X-API-Key header. Same API used by the MCP server and Copilot.
6-Hour Cache
Uses CacheService.getScriptCache() to store API responses for 6 hours. A 50-cell spreadsheet makes at most 50 API calls on first load, then zero until cache expires. Clear manually via the NZXplorer menu.
Key in Script Properties
Your API key is stored in PropertiesService.getScriptProperties(), not in the spreadsheet. It is not visible to collaborators who have edit access but not Apps Script access.
Error Codes
| Error | Meaning | Fix |
|---|---|---|
| #NO_DATA | No data available for this ticker/metric combination | Check the ticker symbol and metric name are correct |
| #AUTH_ERROR | API key is missing, invalid, or expired | NZXplorer menu > Set API Key |
| #RATE_LIMIT | Too many API requests in the last minute | Wait 60 seconds and recalculate (Ctrl+Shift+F9) |
| #NOT_FOUND | Ticker not recognized or endpoint returned 404 | Verify the ticker is a current NZX-listed company |
| #INVALID_TICKER | Empty or non-string ticker argument | Pass a valid ticker string, e.g. "FPH" |
| #API_ERROR | Server error or network issue | Try again in a few minutes |
Frequently Asked Questions
How do I get an API key?
Sign up at nzxplorer.co.nz/auth and visit your account page. Free tier includes 10 API requests per minute, which is sufficient for most spreadsheet use. Pro ($29/mo) allows 100 requests/min for larger models.
How often does the data refresh?
Data is cached for 6 hours in Google Apps Script cache to stay within Google quotas. Use the NZXplorer menu > Refresh All Data to clear the cache manually. Stock prices update daily; financials update when companies file.
What companies are supported?
All 131 NZX-listed companies are supported. Use standard NZX ticker symbols: FPH, AIR, SPK, MEL, CEN, MFT, etc. The ticker is case-insensitive.
What does "NZD thousands" mean for financial data?
Financial statement values (revenue, profit, assets, etc.) from NZX_FINANCIALS are in NZD thousands, matching the standard NZ annual report convention. A value of 1856000 means $1,856,000,000 ($1.856 billion). Divide by 1000 if you want raw dollars, or multiply by 1000 if you want actual NZD.
Can I use this in Excel or other spreadsheet apps?
This add-on is designed for Google Sheets, which supports custom functions via Google Apps Script. For Excel, you can use the NZXplorer REST API directly with Power Query or Office Scripts. See the API documentation at /developers.
What happens if I exceed the rate limit?
Functions will return #RATE_LIMIT. The 6-hour cache means most spreadsheets make very few actual API calls. A sheet with 50 different formulas makes at most 50 calls on first load, then serves from cache. Wait 60 seconds and recalculate to retry.
Is the Insider Conviction Score (ICS) the same as on the website?
Yes. The ICS is computed from the last 30 insider trades using the same 4-component algorithm: buy/sell ratio (30pts), multi-director alignment (25pts), recency (25pts), and volume intensity (20pts). The calculation runs inside Google Sheets, so it works even without a premium API plan.
Ready to Add NZX Data to Your Spreadsheet?
Copy the script, set your API key, and start using NZX functions in under 2 minutes. Free tier supports 10 requests per minute.
Data sourced from publicly available NZX filings. Our datasets may not be complete. Automated analysis can produce errors. If you believe any data on this page is incorrect, please contact us at hello@nzxplorer.co.nz. For informational purposes only. Not investment advice.