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 | {highlight: 1} | Additional parameters to filter the address results. Add any of the Address Autocomplete API parameters. 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 | {highlight: 1} | Additional parameters to filter the location results. Add any of the Location Autocomplete API parameters. 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 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. Note: The street attribute also includes the Street Type. | State Highway 1 |
street_name | String | Holds the name of the street. | Queen |
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 |
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 |
pxid * | String | Unique address identifier. | 3-.1.1d.2.42.1T.2 |
dpid | String | A unique reference number assigned to each delivery address by NZ Post. | 2668726 |
aims_address_id | String | The unique identifier from Land Information New Zealand (LINZ). | 1518959 |
aims_road_section_id | String | The unique road section identifier from Land Information New Zealand (LINZ). | 323309 |
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 meshblock returned is from the 2013 census. The default data source will change to the 2018 census 3 months after the 2018 census results are released. | 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 |
ur_id | String | Urban rural ID (2018 census only) | 1002 |
ur | String | Urban rural name (2018 census only) | Kaimaumau |
iur_id | String | Urban rural indicator ID (2018 census only) | 21 |
iur | String | Urban rural indicator name (2018 census only) | Rural settlement |
cb_id | String | Community Board ID (2018 census only) | 00101 |
cb | String | Community Board name (2018 census only) | Te Hiku Community |
con_id | String | Constituency ID (2018 census only) | 0101 |
con | String | Constituency name (2018 census only) | Te Hiku Constituency |
maoricon_id | String | Maori Constituency ID (2018 census only) | 0402 |
maoricon | String | Maori Constituency name (2018 census only) | Okurei Maori Constituency |
region_id | String | Region ID (2018 census only) | 04 |
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 |
ta_id | String | Territorial Authority ID (2018 census only) | 060 |
ta * | String | The Territorial Authority in which this address exists. Territorial authorities are the second tier of local government in New Zealand. | Auckland |
tasub_id | String | Territorial Authority Subdivision ID (2018 census only) | 06019 |
tasub | String | Territorial Authority Subdivision name (2018 census only) | Akaroa Subdivision |
ward_id | String | Ward ID (2018 census only) | 06016 |
ward | String | Ward name (2018 census only) | Banks Peninsula Ward |
landwater_id | String | Land/Water ID (2018 census only) | 22 |
landwater | String | Land/Water description (2018 census only) | Inlet |
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 |
success * | Boolean | Indicates if the request was successful or not. | true |
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-jaH156zsvbzhS$Ysdi2AC |
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 meshblock returned is from the 2013 census. The default data source will change to the 2018 census 3 months after the 2018 census results are released. | 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 |
Australian Address metadata
| Property | Type | Description | Example |
|---|---|---|---|
full_address * | String | Full address string. FAQ: alias address vs canonical address. | 13 Neville Street, RYDE NSW 2112 |
id * | String | The unique address identifier. This ID will change following a data refresh. | 8097e3df-a3ab-43ad-bc66-22c8f5812361 |
canonical_address | 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 | 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 | String | Latitude coordinate (in WGS84 format) from the G-NAF dataset, or PAF dataset (for PAF-only addresses). | -37.899031 |
longitude | String | Longitude coordinate (in WGS84 format) from the G-NAF dataset, or PAF dataset (for PAF-only addresses). | 144.999530 |
meshblock | 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 | 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 | 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 | String | The unique persistent identifier of the G-NAF address. | GANSW705051429 |
dpid | String | Australia Post delivery point identifier. Only returned on canonical addresses from Australia Post when parameter paf=1 supplied. | 99119187 |
legal_parcel_id | String | Government legal property description | 10//SP9489 |
lot_identifier | String | Identifies a specific lot on a site. Can be an alpha, number or a combination. | 3 |
box_identifier | String | The number portion of a PO Box address | 123 |
box_type | 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 | String | Holds the address element that identifies the name of a site or building. | Kenilworth Police Station |
level_type | String | Describes the level type within a multi-level building. | Basement |
level_number | String | Identifies a specific level within a multi-level building. Can be an alpha, number or a combination. | 3 |
unit_type | String | Describes the category of a sub-dwelling. | Suite |
unit_identifier | String | Identifies a specific sub-dwelling. Can be an alpha, number or a combination. | 2 |
street_number_1 | String | The number of the building on the street. | 1703 |
street_number_2 | String | Holds the upper bound when this is a ranged address. For single number addresses this field is null | 1705 |
street | 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 | String | Holds the name of the street. Note: This attribute does not include the street type or suffix. | Queen |
street_type | String | The type of street. | Street |
street_suffix | String | The suffix of the street. Typically contains a compass direction. | North |
locality_name * | String | The locality/suburb of this address. | KATOOMBA |
state_territory * | String | The Australian state or territory where the address is located. | NSW |
postcode * | String | Holds the four digit postcode. | 0983 |
address_line_1 * | String | First line of the non-locality/state/postcode portion of the address | Unit 209 |
address_line_2 | 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 * | Boolean | Indicates if the request was successful or not. | true |
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 |
* Attributes marked with an asterisk will always be present in a successful API response.