Market Rent API

The Market Rent API provides statistics derived from information gathered from bonds lodged with Tenancy Services. Requests to the API can define parameters including time periods, locations, and area/location granularity, enabling the user to obtain the statistics they need while preserving the privacy of the underlying data.  Responses can be received in JSON or CSV formats.

The API provides the convenience of self service and gives access to a greater range of information than currently available on the Tenancy Services website.

Market rent explanatory information

Market rent statistics are derived from information gathered from bonds lodged with Tenancy Services.  The results may not be a true indication of the rental market, because they only reflect properties where bonds are lodged.

The data provided shows recent market rents for non-government owned properties for which Tenancy Services holds information. It should not be used to determine the market rent of any property or for any other purpose except as an indication of the non-government rental market based on bonds lodged with Tenancy Services.

Tenancy Services is a part of the Ministry of Business, Innovation and Employment (MBIE). MBIE accepts no liability for use of this data other than for the purpose referred to above. 

The Market Rent API is a service that provides statistics derived from information gathered from bonds lodged with Tenancy Services.  The statistical data can be returned in either JSON or CSV format via the Accept HTTP header property.  By default JSON is returned but the statistics service will return CSV format if the Accept header is set to text/csv.

A sandbox environment is provided for use while doing development and testing of any software that integrates the Market Rent API.

Performance: Note that getting market rent statistics is a time consuming operation that can take up to two minutes to complete for the first time a complex query is run.

Using the API

Follow these steps to get up and running:

Read the technical details

View the API definition in our developer portal here. You can also download the definition for viewing in Swagger Editor, SwaggerHub, or other tools.

Subscribe to the API

Log in and subscribe to the Market Rent API product. Our API support team may request further information before the subscription can be approved.

Generate an API subscription key and call the API

For full details on how to generate an API subscription key, and optionally an OAuth2 bearer token for additional security, please see here.

Once your subscription has been approved you will be able use your API credentials to successfully call the API. Use the sandbox key and sandbox endpoints in your software development. Once you've completed testing simply use your production keys to access the live service.


There are alternative methods for accessing the API that don't require you to develop your own software. If you use R for statistical computing you can use the httr library to call the API and retrieve data into a tibble. Or you can use a web browser with a suitable plugin that allows you to add custom headers when visiting web pages.

R example

Get statistics at regional council granularity for the month of September 2020 into a tibble, and also save the data as a CSV file

library(httr)
library(readr)
url<-"https://api.business.govt.nz/gateway/tenancy-services/market-rent/v2/statistics?period-ending=2020-09&num-months=1&area-definition=regional-council-2019"
response <- GET(url, add_headers(Ocp-Apim-Subscription-Key = "YOUR_SUBSCRIPTION_KEY", Accept = "text/csv"), timeout(120), verbose())
mktRent <- content(response, type = "text/csv", encoding = "UTF-8")
write.csv(mktRent, "MarketRent-202009-1month.csv")

Web Browser Example

Using Google Chrome with the Modify Header Value extension you can configure the browser to always add the required Authorization and Accept headers to requests to the Market Rent API. A CSV file can then be downloaded by entering the API address including the desired query parameters into the Chrome address bar. Steps to achieve this:

  1. Add the Modify Header Value extension to Google Chrome. 

  2. Open the Options for the extension.

  3. Add two new headers for the URL https://api.business.govt.nz/gateway/tenancy-services/market-rent/v2/* using the following header name and header values.

  4. The first header name is 'Accept' and value is 'text/csv'

  5. The second header name is 'Ocp-Apim-Subscription-Key' and value is "YOUR_SUBSCRIPTION_KEY", where YOUR_SUBSCRIPTION_KEY is the subscriber key you have set up for yourself when subscribing to the API product. You can find this when logged in through the My Subscriptions page after your subscription has been approved.

  6. Enter the address into the browser for the Market Rent query you wish to download. E.g. get statistics at regional council granularity for the (1) month of October 2020
    https://api.business.govt.nz/gateway/tenancy-services/market-rent/v2/statistics?period-ending=2020-10&num-months=1&area-definition=regional-council-2019

  7. The CSV will be downloaded by the browser.

Mandatory Request Parameters

The mandatory request parameters are:

  • Specification of the period of time is via two parameters:

    • period-ending - period end date specified in the format yyyy-mm (e.g. 2020-10).

      Note: this value must be earlier than the month prior to the current date. As bonds may be lodged up to 23 working days from the start of the tenancy, the statistics for the current and prior months will vary depending on when the query is run, as more bonds are lodged and processed over time.

    • num-months - the number of months of data to include.  Must be between 1 and 24.

  • area-definition - this specifies the granularity of the areas the statistics are reported by.  This can be one of the (label or code) values returned by GET /area-definitions operation, for example 'regional-council-2019', 'territorial-authority-2019', 'SAU2019', etc.

All other request parameters are optional and control the specific statistics returned, the factors the statistics are reported by or specify the particular areas of interest. 

Statistics Available

The following statistics are available (JSON labels):

  • nLodged - Number of bonds lodged at some point in the period.  Note random rounding is applied to this value.

  • nClosed - Number of bonds closed at some point in the period.  Note random rounding is applied to this value.

  • nCurr - Total number of bonds active at the end of the period.  Note random rounding is applied to this value.

  • mean - Mean weekly rent of bonds lodged within the period.

  • lq - Lower Quartile weekly rent; weekly rent of the bond that is at the 25th percentile of bonds lodged in the period 

  • med - Median weekly rent; weekly rent of the bond that is at the 50th percentile of bonds lodged in the period 

  • uq - Upper Quartile weekly rent; weekly rent of the bond that is at the 75th percentile of bonds lodged in the period 

  • sd - Sample Standard Deviation of weekly rent

  • brr - Mean Bond/Rent Ratio

  • lmean - Mean of natural logarithm weekly rent.  Note that exp(lmean) == Geometric mean is a good estimate of the median as rent is log normally distributed so can be thought of as the "Synthetic median" of market rent consistent with the other synthetic statistics below

  • lsd - sample standard deviation of natural logarithm weekly rent of bonds lodged within the period

  • slq - Synthetic Lower Quartile Weekly Rent.  This is defined as exp(lmean + qnorm(0.25) * lsd) and is a reasonable estimate of the lower quartile 

  • suq - Synthetic Upper Quartile Weekly Rent.  This is defined as exp(lmean + qnorm(0.75) * lsd) and is a reasonable estimate of the upper quartile 

Report Factors

The statistics are reported by:

  • Area label/location.  The values of this depend on the area-definition specified and can be obtained via the GET /area-definitions/{area-definition} operation (ALL is the label for all areas in the area definition (or subset selected via the area-codes or area-labels parameters.)

  • Dwelling type.  Can take the values: Apartment, Boarding House, Flat, House, Room, ALL  (ALL is for statistics across all Dwelling Types. In most cases if the dwelling type is not entered in a bond lodgement the dwelling is assumed to be a house)

  • Number of bedrooms.  Can take the values: 1, 2, 3, 4, 5+, NA (NA means Not Available)

Note that statistics for 'ALL' labels, across all aggregated combinations of the above factors, will only be present if the request parameter include-aggregates is set to true in the get statistics operation.

Log normal distribution and "Synthetic" statistics explained

For those interested in modelling rent it should be noted that the log normal distribution is a better fit for market rent than the standard normal distribution.  In addition the values for rent tend to cluster around multiples of $10 so that the trend, over time, for the lower and upper quartiles and median can remain flat for significant periods of time.  Because of this lmean and lsd are more useful than the mean and sd for modelling and the "Synthetic" (lower quartile and upper quartile) statistics, which are estimates of the lower quartile and upper quartile derived from the log normal distribution, are better behaved indicators of change.  Note however, the synthetic lower quartile (slq) tends to slightly underestimate the lower quartile (lq) while the synthetic upper quartile (suq) slightly over estimates the upper quartile (uq). 

Privacy protection

Privacy is protected by the following mechanisms:

  • Suppression: Any summary statistics where the number of bonds lodged in the period is less than 5 are suppressed

  • Random rounding: All (unsuppressed) counts (nlodged, nClosed ,nCurr) are also randomly rounded to a number divisible by three as follows:

    • If the values is already a multiple of three it is unchanged, otherwise:

    • it is rounded to the nearest multiple of three with a probability of two-thirds (applied approximately two-thirds of the time)

    • it is rounded to the second closest multiple of three with a probability of one-third (applied approximately one-third of the time).

The random rounding protects against the recalculation of small counts from differencing large counts and retains almost all of the statistical properties of the table by adding only a little noise to the larger counts.  Note also that each value in a table is rounded independently, including the totals. This means that the marginal totals can differ slightly from the corresponding sum of the rows or columns, i.e. if the columns or rows in a table are added, they will not always equal the total given. 

Limiting statistics to certain defined areas

If the user wishes to only receive statistics for a subset of area labels defined for a given area granularity (for example to reduce data transfer etc.) then the request can specify a list of area labels to report on via the 'area-labels' request parameter (or alternatively specify a list of 'area-codes').  The valid area labels (and codes) for a given area-definition can be obtained via the GET /area-definition/{area-definition}/area-labels operation where {area-definition} is one of the available values for area definition (which in turn is obtainable from the GET /area-definitions operation).  Alternatively, with the exception of the 'internet-market-rent-yyyy' area definitions, these can be found from the Stats NZ Geographic Data Service.

The 2016 and 2019 versions of Stats NZ geographic areas are both available in the API, though users are encouraged to use the 2019 versions to receive the most relevant data.

Specifying user defined areas

The API supports a range of area definitions (the definitive list can be obtained via the GET /area-definitions operation), with the Statistical Area 2 (SA2) boundary set being the most fine-grained area definition available. However, you may wish to define your own customised area boundaries for the statistics to be reported on.

In order to specify user defined areas it needs to be understood that user defined area labels must be defined as aggregations of one or more SA2 boundaries.

To get results for a user defined area requires the following steps:

  1. Obtain the list of area labels and numeric codes for the SA2 area granularity via the GET /area-definitions/SAU2019 or get the labels and corresponding numeric codes from the Geographic Data Service.

  2. Create a set of user defined labels as a comma seperated string for each user defined area, in the form "{user-defined-label} ({sau-1},{sau-2},...)" where {user-defined-label} is any valid string (not including the parentheses characters) and {sau-1}, {sau-2}, ... is a parentheses bound, whitespace tolerant, comma seperated list of SAU codes that are exclusively across all elements. Note also that each SAU value can only be defined in at most one user defined area label (i.e. no duplicates). For example to create a user defined area, 'My Hokitika', as the union of the Hokitika Rural and Hokitika SAU labels the following array element could be used 'My Hokitika (311700, 311500)'.

  3. In the GET request for statistics specify the value 'user-defined' for the 'area-definition' query parameter and pass an array of user defined label definitions (as above) for the 'user-defined-area-mappings' query parameter. For example to report on two user defined areas named 'My Hokitika' and 'My Greymouth', for the first half of 2020, the following could be used: GET /statistics?period-ending=2020-06&num-months=6&area-definition=user-defined&user-defined-area-mappings=My Hokitika(311700, 311500),My Greymouth(310100, 310300, 310800)