Documentation - Widget documentation

AddressFinder.Widget class

Constructor

Constructor	Parameters	Description
`AddressFinder.Widget()`	`input:Element`, `api_key:String`, `country_code:String`, `options?:Object`	Attaches a new widget to the specified `input` element.

Methods

Method	Parameters	Return Value	Description
`on()`	`event_name:String`, `callback:Function`	AddressFinder.Widget	Subscribes to a specified event.
`trigger()`	`event_name:String`, `arguments`…	AddressFinder.Widget	Manually fires a specified event.
`setOption()`	`option_name:String`, `value:*`	AddressFinder.Widget	Sets an option after the widget has been initialised.
`getOption()`	`option_name:String`	AddressFinder.Widget	Gets the current value of the specified option.
`addService()`	`name:String`, `search_function:Function`	AddressFinder.Service	Function to add an additional third-party search.
`disable()`		AddressFinder.Widget	Disables the AddressFinder widget. The autocomplete function will stop operating until it is re-enabled.
`enable()`		AddressFinder.Widget	Re-enables a disabled AddressFinder widget.

Options

Option	Type	Default	Description
`address_params`	Object	`{strict: "2"}`	Additional parameters to filter the address results. Add any of the Address params. The Code Demos page has some good examples.
`address_metadata_params`	Object	`nil`	Additional parameters to adjust the values returned from the Address Metadata API. Add any of the Address Metadata API parameters.
`base_url`	String	`https://api.addressfinder.io`	The base URL endpoint for API calls and CSS resources.
`canonical`	Boolean	`true`	Force the selection of the canonical address when an aliased address is selected.
`container`	Object	`document.body`	The element that wraps in input field that AddressFinder will use. This is useful when embedding the widget within a scrolling panel. The Code Demos page has some good examples.
`empty_class`	String	`'af_empty'`	CSS class name to be applied to the `li` element containing the empty_content message.
`empty_content`	String	`No addresses were found. This could be a new address, or you may need to check the spelling. Learn more`	Message to display to users when there are no found addresses or locations.
`footer_class`	String	`'af_footer'`	CSS class name to be applied to the `li` element containing the footer.
`hover_class`	String	`'af_hover'`	CSS class name to be applied to the `li` element of a highlighted result.
`ignore_returns`	Boolean	`true`	Ignore the use of the enter key when no list item is selected.
`item_class`	String	`'af_item'`	CSS class name to be applied to the `li` element of a result.
`list_class`	String	`'af_list'`	CSS class name to be applied to the `ul` element containing the results.
`location_params`	Object	`{}`	Additional parameters to filter the location results. Add any of the Location Params. The Code Demos page has some good examples.
`manual_style`	Boolean	`false`	If true, the widget will not embed the default stylesheet, allowing a custom stylesheet to be used. (Can only be set when widget is constructed).
`max_results`	Integer	`10`	Maximum number of results to display.
`position`	String	`'absolute'`	Use a different positioning value for the list_class element. When embedding AddressFinder within a `fixed` position element, using a matching `fixed` position value will ensure the popup list appears below the input element.
`show_addresses`	Boolean	`true`	Set to false to hide address results.
`show_locations`	Boolean	`false`	Set to true to return location (street, suburb, city and region) results.
`show_nearby`	Boolean	`false`	Enable the nearby address helper (uses device's GPS to suggest addresses at current location). This feature is only available for New Zealand addresses.
`show_points_of_interest`	Boolean	`false`	Set to true to return points of interest (e.g. hospitals, schools and churches) results. This feature is only available for New Zealand addresses.

Events

Event	Callback Arguments	Description
`"result:select"`	`selectedAddress:String`, `metadata:Object`	Fired when any result is selected. The metadata value returned depends on the type of address selected, which depends on the search criteria supplied. The metadata could be either Australian Address metadata, Australian Location metadata, New Zealand Address metadata, New Zealand Location metadata or New Zealand Point of Interest metadata
`"address:select"`	`selectedAddress:String`, `metadata:Object`	Just like `"result:select"`, but only fired when an address is selected. The metadata could be either Australian Address metadata or New Zealand Address metadata
`"address:select:pre"`	`selectedAddress:String`, `metadata:Object`	Fired immediately when an address is selected, before an info request for extended data is made.
`"location:select"`	`selectedLocation:String`, `metadata:Object`	Just like `"result:select"`, but only fired when a location is selected. The metadata could be either Australian Location metadata or New Zealand Location metadata
`"location:select:pre"`	`selectedLocation:String`, `metadata:Object`	Fired immediately when an location is selected, before an info request for extended data is made.
`"point_of_interest:select"`	`selectedPointOfInterest:String`, `metadata:Object`	Just like `"result:select"`, but only fired when a point of interest is selected. The metadata will be New Zealand Point of Interest metadata
`"point_of_interest:select:pre"`	`selectedPointOfInterest:String`, `metadata:Object`	Fired immediately when an point of interest is selected, before an info request for extended data is made.
`"results:update"`		Fired when all services have updated their results.
`"results:empty"`		Fired when there are no results to display.

AddressFinder.Service class

Constuctor

AddressFinder.Service is returned from the AddressFinder.Widget#addService method.

Methods

Method	Parameters	Return Value	Description
`on()`	`event_name:String`, `callback:Function`	AddressFinder.Service	Subscribes an a specified event.
`trigger()`	`event_name:String`, `arguments`…	AddressFinder.Service	Manually fires a specified event.
`setOption()`	`option_name:String`, `value:*`	AddressFinder.Service	Sets an option after the widget has been initialised.
`getOption()`	`option_name:String`	AddressFinder.Service	Gets the current value of the specified option.

Options

Option	Type	Default	Description
`renderer`	Function		Allows a function to be defined to format how the result will be displayed. The function will be passed two arguments, the value and the data, and must return a string.

Events

Event	Callback Arguments	Description
`"result:select"`	`selectedAddress:String`, `metadata:Object`	Fired when a result from this service is selected.

New Zealand Address Params

Property	Type	Description
`delivered`	String	This filter determines if the results are either delivered or not delivered by NZ Post.
`post_box`	String	This filter includes/excludes PO Box style addresses.
`rural`	String	This filter includes/excludes rural/urban addresses.
`region_code`	String	Only return addresses within the boundary of the selected region (Regional Authority).

New Zealand Address metadata

Property	Type	Description	Example
`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
`building_name`	String	Holds the building or property name.	Miban Building
`unit_type`	String	Describes the category of a sub-dwelling.	Flat
`unit_identifier`	String	Identifies a specific sub dwelling. Can be alpha, number or a combination.	1
`floor`	String	The level number and level type in a multi-story building.	Level 19
`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 as supplied by Land Information New Zealand or NZ Post. Note: The street attribute also includes the Street Type.	Pūrākaunui Road
`street_name`	String	Holds the name of the street as supplied by Land Information New Zealand or NZ Post.	Pūrākaunui
`post_street`	String	Holds the street name and type from NZ Post, it will be omitted if the address is not delivered to by NZ Post.	Purakaunui Road
`post_street_name`	String	Holds the street name from NZ Post, it will be omitted if the address is not delivered to by NZ Post.	Purakaunui
`street_type`	String	The type of street.	Avenue
`suburb`	String	The suburb or locality of the address as assigned by Land Information New Zealand.	Warkworth
`city`	String	The city, town or locality name as assigned by Land Information New Zealand.	Warkworth
`box_type`	String	The type of PO Box/CMB/Private Bag/Counter Delivery.	PO Box
`lobby_name`	String	The name of the NZ Post outlet or Agency outlet where the PO Box, Private Bag or Counter Delivery is located.	Fendalton
`rd_number`	String	The rural delivery number assigned by NZ Post to a rural address.	4
`post_suburb`	String	Name of the suburb when supplied by NZ Post.	Manukau
`mailtown`	String	Name of the town/city when supplied by NZ Post.	Warkworth
`postcode`	String	Holds the four digit postcode.	0983
`dpid`	String	A unique reference number assigned to each delivery address by NZ Post.	2668726
`primary_parcel_id`	String	The unique identifier of the portion of land associated with the selected address.	3866475
`aims_address_id`	String	The unique identifier from Land Information New Zealand (LINZ).	1518959
`x`	String	Longitude coordinate (in WGS84 format).	174.643199
`y`	String	Latitude coordinate (in WGS84 format).	-36.426956
`meshblock`	String	The meshblock identifier for the requested census dataset (see `census` parameter). If not specified, the Census parameter will default to 2018.	146004
`sa1_id`	String	Statistical area 1 (2018 census only)	7000001
`sa2_id`	String	Statistical area 2 ID (2018 census only)	100200
`sa2`	String	Statistical area 2 name (2018 census only)	Rangaunu Harbour
`rural`	Boolean	An indicator to help determine if this address is located in a rural setting. Note: Different courier companies have different rural/urban boundaries so this determination should be confirmed by your delivery agent.	true
`ur`	String	Urban rural name (2018 census only)	Kaimaumau
`ur_id`	String	Urban rural ID (2018 census only)	1002
`iur`	String	Urban rural indicator name (2018 census only)	Rural settlement
`iur_id`	String	Urban rural indicator ID (2018 census only)	21
`aims_road_section_id`	String	The unique road section identifier from Land Information New Zealand (LINZ).	323309
`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
`region_id`	String	Region ID (2018 census only)	04
`ta`	String	The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand.	Auckland
`ta_id`	String	Territorial Authority ID (2018 census only)	060
`con`	String	Constituency name (2018 census only)	Te Hiku Constituency
`con_id`	String	Constituency ID (2018 census only)	0101
`maoricon`	String	Maori Constituency name (2018 census only)	Okurei Maori Constituency
`maoricon_id`	String	Maori Constituency ID (2018 census only)	0402
`ward`	String	Ward name (2018 census only)	Banks Peninsula Ward
`ward_id`	String	Ward ID (2018 census only)	06016
`cb`	String	Community Board name (2018 census only)	Te Hiku Community
`cb_id`	String	Community Board ID (2018 census only)	00101
`tasub`	String	Territorial Authority Subdivision name (2018 census only)	Akaroa Subdivision
`tasub_id`	String	Territorial Authority Subdivision ID (2018 census only)	06019
`landwater`	String	Land/Water description (2018 census only)	Inlet
`landwater_id`	String	Land/Water ID (2018 census only)	22
`address_line_1`	String	First line of the non-suburb/city/postcode portion of the address	Unit 2
`address_line_2`	String	Second line of the non-suburb/city/postcode portion of the address.	1703A State Highway 1
`pxid`	String	Unique address identifier.	3-.1.1d.2.42.1T.2
`success`	Boolean	Indicates if the request was successful or not.	true

New Zealand Location Params

Property	Type	Description
`street`	String	This filter restricts results to streets
`suburb`	String	This filter restricts results to suburbs.
`city`	String	This filter restricts results to cities.
`region`	String	This filter restricts results to regions.
`region_code`	String	Only return locations within the boundary of the selected region (Regional Authority).
`strict`	String	Determines how closely matched the results should be to the `q` parameter.

New Zealand Location metadata

Property	Type	Description	Example
`a`	String	Canonical location as supplied by Land Information New Zealand.	Seaview Road, Glenfield, Auckland
`pxid`	String	Unique location identifier.	1-.6.M.1.M
`street`	String	Holds the full name of the street. Note: The street attribute also includes the Street Type.	Seaview Road
`suburb`	String	The suburb or locality of the address as assigned by Land Information New Zealand.	Glenfield
`city`	String	The city, town or locality name as assigned by Land Information New Zealand.	Auckland
`region`	String	The Regional Authority in which this location exists. Note: Regional Authorities are the top tier of local government in New Zealand.	Auckland Region
`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

New Zealand Point of Interest metadata

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
`unit_identifier`	String	Identifies a specific sub dwelling. Can be alpha, number or a combination.	1
`unit_type`	String	Describes the category of a sub-dwelling.	flat
`floor`	String	The level number and level type in a multi-story building.	Level 19
`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 requested census dataset (see `census` parameter). If not specified, the Census parameter will default to 2018.	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
`dpid`	String	A unique reference number assigned to each delivery address by NZ Post.	2668726
`box_type`	String	The type of PO Box/CMB/Private Bag/Counter Delivery.	PO Box
`lobby_name`	String	The name of the NZ Post outlet or Agency outlet where the PO Box, Private Bag or Counter Delivery is located.	Fendalton
`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

Australian Address Params

Property	Type	Description
`gnaf`	String	Returns physical addresses from the GNAF dataset (supplied by the Australian Government).
`au_paf`	String	Returns postal addresses from the PAF dataset. These are addresses which Australia Post deliver mail to and StarTrack and eParcel deliver parcels to.
`post_box`	String	Return PO Box style addresses. This includes `PO Box`, `Locked Bag`, `GPO Box`, `CMB`, `RMS`, `Care PO`, `MS` and `RSD`. Used with the au_paf=1 filter above.
`canonical`	String	Return canonical and/or alias addresses - this allows for vanity suburbs, historic street names, and more. FAQ: What is the difference between canonical and alias addresses
`state_codes`	String	Filter the results according to the states or territories. Use a comma to separate multiple values

Australian Address metadata

Key

GNAF Returned (if present) when searching the gnaf database.

PAF Returned (if present) when searching the au_paf database.

Property	Type	Description	Example
`full_address` GNAF PAF	String	Full address string. FAQ: alias address vs canonical address.	13 Neville Street, RYDE NSW 2112
`id` GNAF PAF	String	The unique address identifier. This ID will change following a data refresh.	8097e3df-a3ab-43ad-bc66-22c8f5812361
`canonical_address` GNAF PAF	String	The canonical or official full address string associated with this address. Can differ from the full_address in either street number, locality name or state name. FAQ: alias address vs canonical address.	11-15 Neville Street, RYDE NSW 2112
`canonical_address_id` GNAF PAF	String	The ID of the canonical or official address associated with this search result. Note: The ID and Canonical Address ID will be identical when the search result is canonical. FAQ: alias address vs canonical address.	d70230a9-a3d8-402f-971e-1b798d00f2f5
`latitude` GNAF PAF	String	Latitude coordinate (in WGS84 format).	-37.899031
`longitude` GNAF PAF	String	Longitude coordinate (in WGS84 format).	144.999530
`lot_identifier` GNAF PAF	String	Identifies a specific lot on a site. Can be an alpha, number or a combination.	3
`box_identifier` GNAF PAF	String	The number portion of a PO Box address	123
`box_type` GNAF PAF	String	The type portion of a PO Box address, including `PO Box`, `Locked Bag`, `GPO Box`, `CMB`, `RMS`, `Care PO`, `MS` and `RSD`	PO Box
`site_name` GNAF PAF	String	Holds the address element that identifies the name of a site or building.	Kenilworth Police Station
`level_type` GNAF PAF	String	Describes the level type within a multi-level building.	Basement
`level_number` GNAF PAF	String	Identifies a specific level within a multi-level building. Can be an alpha, number or a combination.	3
`unit_type` GNAF PAF	String	Describes the category of a sub-dwelling.	Suite
`unit_identifier` GNAF PAF	String	Identifies a specific sub-dwelling. Can be an alpha, number or a combination.	2
`street_number_1` GNAF PAF	String	The number of the building on the street.	1703
`street_number_2` GNAF PAF	String	Holds the upper bound when this is a ranged address. For single number addresses this field is `null`	1705
`street` GNAF PAF	String	Holds the full name of the street. This attribute is a composite of the street name, the street type, and the street suffix if present.	Queen Street North
`street_name` GNAF PAF	String	Holds the name of the street. Note: This attribute does not include the street type or suffix.	Queen
`street_type` GNAF PAF	String	The type of street.	Street
`street_suffix` GNAF PAF	String	The suffix of the street. Typically contains a compass direction.	North
`locality_name` GNAF PAF	String	The locality/suburb of this address.	KATOOMBA
`state_territory` GNAF PAF	String	The Australian state or territory where the address is located.	NSW
`postcode` GNAF PAF	String	Holds the four digit postcode.	0983
`address_line_1` GNAF PAF	String	First line of the non-locality/state/postcode portion of the address	Unit 209
`address_line_2` GNAF PAF	String	Second line of the non-locality/state/postcode portion of the address. This will be `null` for addresses without a unit/level/etc number.	274 Harbour Drive
`success` GNAF PAF	Boolean	Indicates if the request was successful or not.	true
`dpid` PAF	String	Australia Post delivery point identifier.	99119187
`lga_name` GNAF	String	The name of the Local Government Area in which the address is located. These values are provided by the ABS and are an approximation of the gazetted local government boundaries. Code example - collect LGA data	Bundaberg
`lga_type_code` GNAF	String	The code relating to the type (or status) of the Local Government Area. Codes used are Area `A`, Aboriginal Council `AC`, Borough `B`, City `C`, District Council `DC`, Municipality / Municipal Council `M`, Regional Council `R` or `RegC`, Rural City `RC`, Shire `S` and Town `T`.	DC
`legal_parcel_id` GNAF	String	Government legal property description.	10//SP9489
`meshblock` GNAF	String	The meshblock identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census. The format is `MB`, followed by a 2 digit year identifier, followed by the 11 digit meshblock identifier. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.	MB1610671120000
`sa1_id` GNAF	String	The statistical area (SA1) identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.	12602159143
`sa2_id` GNAF	String	The statistical area (SA2) identifier in which the address is located. These values are provided by the Australian Bureau of Statistics and are updated for each census. Use the `census` parameter to select from either the `2011` and `2016` census. Defaults to `2016` if not provided.	126021591
`gnaf_id` GNAF	String	The unique persistent identifier of the G-NAF address.	GANSW705051429

Australian Location Params

Property	Type	Description
`location_types`	String	Show only locations of the supplied type. Use a comma to separate multiple values.
`state_codes`	String	Filter the results according to the states or territories. Use a comma to separate multiple values.

Australian Location metadata

Property	Type	Description	Example
`full_location`	String	Full location string.	Mathers Road East, WALKERVILLE VIC 3959
`location_type`	String	The kind of location. Valid values include street, locality or state.	street
`latitude`	String	Latitude coordinate (in WGS84 format).	-38.77287906
`longitude`	String	Longitude coordinate (in WGS84 format).	146.10907797
`street_name`	String	Holds the name of the street. Note: This attribute response does not contain the street type.	Mathers
`street_type`	String	The type of street.	Road
`street_suffix`	String	The suffix of the street. Typically contains a compass direction.	East
`street`	String	The full street name. Note: This attribute response contains the street name, street type and street suffix.	Mathers Road East
`locality_name`	String	The locality/suburb of this address.	WALKERVILLE
`state_territory`	String	The Australian state or territory containing the location	VIC
`postcode`	String	The postcode assigned to a locality (for 'locality' locations), or to the locality a street is in (for 'street' locations).	3959
`success`	Boolean	Indicates if the request was successful or not.	true