Points of Interest (NZ only)

Points of Interest is a New Zealand only search feature which allows a user to search 'points of interest', such as hospitals, libraries, parks, businesses etc rather than specific addresses. This service returns points of interest, with associated addresses, in place of, or in addtion to regular addresses being searched.

This service is only available in New Zealand.

This page outlines how to integrate the Points of Interest Widget.
For advanced integration utilise the Points of Interest Autocomplete API and POI Metadata API.

Configure with widget options and select metadata returned when point of interest is selected.

How to integrate

You’ll need access to update the website or form where you want to add the widget and have an Addressfinder account.

Copy and paste the code snippet below into the HTML of your webpage, ideally just before the closing </body> tag.
Replace 'search_field_id' with the ID of your first address field (eg, address_1).
Replace your_license_key with your Addressfinder license key. You can find it in the Addressfinder Portal. If you don't have an Addressfinder account, sign up for a free trial.
Update the code snippet with the IDs of the fields you are using to capture the selected point of interest Name and Address.
Test.

Points of interest autocomplete code snippet

Points of interest widget code snippet
<script>
(function() {
    var widget, initAddressFinder = function() {
        widget = new AddressFinder.Widget(

// Step 2 - Replace 'search_field_id' with the ID of your POI search field.
            document.getElementById('search_field_id'),

// Step 3 - Replace `your_license_key` with your Addressfinder license key.
            'your_license_key',
            'NZ', {
                "show_addresses": false,
                "show_points_of_interest": true
            }
        );

// Step 4 - Update the lines below with the IDs of the fields you want the information to be populated into.
        widget.on('points_of_interest:select', function(selectedPOI, metaData) {
            let selected = new AddressFinder.NZSelectedAddress(metaData.a, metaData);
            document.getElementById('poi_and_addrs1_field_id').value = metaData.name + ', ' + selected.address_line_1();
            document.getElementById("suburb_field_id").value = selected.suburb();
            document.getElementById("city_field_id").value = selected.city();
            document.getElementById("postcode_field_id").value = selected.postcode();
        });
    };

    function downloadAddressFinder() {
        var script = document.createElement('script');
        script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
        script.async = true;
        script.onload = initAddressFinder;
        document.body.appendChild(script);
    };

    document.addEventListener('DOMContentLoaded', downloadAddressFinder);
})();
</script>

Points of Interest autocomplete options

Limit the number of search results to display in the drop down

By default, the widget will return and display up to 10 points of interest in the search results. To display more or less than the default, include the max address_param and the number of addresses you wish to display, in the widget code. Also include the max_results widget param in the code as this gives the widget permission to display these extra addresses. Use any whole number between 1 and 100.

Display up to 20 points of interest example
      "NZ",
      { show_addresses: false,
        show_points_of_interest: true,
              points_of_interest_params: {
          max: 20
        },
        "max_results": "20"
      }
    );

See an example of this on CodePen.

Collecting metadata when Point of Interest selected

As well as the POI Name and Address, this service also returns a variety of other information of value. View the list of metadata available for collection below. This information in returned in the response be default so to collected it, specify in the widget code which data you want and where to populate it.

See this example showing the collection of metadata on selection of the POI.

Points of Interest Parameters

Property	Type	Description	Default Value
`max`	Integer	The maximum number of results to return. A number between 1 and 100.	10

Points of Interest Metadata Response

Property	Type	Description	Example
`name`	String	The name of the point of interest	Whangarei Hospital
`pxid`	String	Unique point of interest identifier.	3-.1.1d.2.42.1T.2
`a`	String	Canonical address as supplied by Land Information New Zealand or NZ Post.	Unit 2, 1703A State Highway 1, Warkworth 0983
`postal`	String	Associated postal address when supplied by NZ Post. Field will be omitted if this address is not delivered to by NZ Post. FAQ: postal address vs 'a' address.	Unit 2, 1703A State Highway 1, RD 3, Warkworth 0983
`number`	String	The street number of the address. Also populated with the box number for PO Box type addresses.	1703
`alpha`	String	Holds the alpha component of a street number. In the address 1B High Street, B is the alpha.	B
`street`	String	Holds the full name of the street. Note: The street attribute also includes the Street Type.	State Highway 1
`street_type`	String	The type of street.	avenue
`building_name`	String	Holds the building or property name.	Miban Building
`suburb`	String	The suburb or locality of the address as assigned by Land Information New Zealand.	Warkworth
`post_suburb`	String	Name of the suburb when supplied by NZ Post.	Manukau
`city`	String The city, town or locality name as assigned by Land Information New Zealand.	Warkworth
`mailtown`	String	Name of the town/city when supplied by NZ Post.	Warkworth
`ta`	String	The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand.	Auckland
`region`	String	The Regional Authority in which this address exists. Note: Regional Authorities are the top tier of local government in New Zealand.	Auckland Region
`rd_number`	String	The rural delivery number assigned by NZ Post to a rural address.	4
`postcode`	String	Holds the four digit postcode.	0983
`meshblock`	String	The meshblock identifier for the default census dataset.	146004
`address_pxid`	String	Address identifier for the address of this point of interest.	2-.F.11.8.G.4
`aims_address_id`	Integer	The unique identifier from Land Information New Zealand (LINZ)	103524
`x`	String	Longitude coordinate (in WGS84 format).	174.643199
`y`	String	Latitude coordinate (in WGS84 format).	-36.426956
`success`	Boolean	Indicates if the request was successful or not.	true

Widget integration guide