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. |
setCountry() |
country_code:String |
AddressFinder.Widget | Sets a country 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 | {gnaf: "1"} |
Additional parameters to filter the address results. NZ Address params, AU Address params and International Address params. The Code Examples page has some good examples. |
address_metadata_params |
Object | nil |
Additional parameters to adjust the values returned with address metadata. NZ Address Metadata params, AU Address Metadata params, International Address Metadata params. |
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 and city) results. |
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. |
"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. |
Address Params
| Property | Type | Description |
|---|---|---|
source |
String | Determines the source of the addresses being searched and returned. |
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 source 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 |
max |
Integer | The maximum number of results to return. A number between 1 and 100. The default is 10 results. |
Address Metadata Params
| Property | Type | Description | Default value |
|---|---|---|---|
source |
String | Determines the source of the address and metadata returned. | gnaf,paf |
GNAF |
Returns the physical address and metadata from the GNAF address dataset (default). | gnaf | |
PAF |
Returns postal address and metadata from the Australia Post postal address file. | paf | |
Combined |
Returns the address and metadata from the dataset associated with the queried address. | gnaf,paf | |
gps |
String | Request GPS coordinates for latitude and longitude be returned when available |
0 |
Yes |
GPS coordinates wil be included in the response | 1 | |
No |
0 | ||
census |
String | Used to determine which census year’s statistical area identifiers (Meshblock, SA1 & SA2) will be returned in the response. Defaults to 2016 if omitted. |
|
2016 |
to collect 2016 census related metadata | 2016 | |
2021 |
to collect 2021 census related metadata | 2021 |
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
|
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). | -37.899031 |
longitude
|
String | Longitude coordinate (in WGS84 format). | 144.999530 |
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 |
address_line_combined
|
String | A combination of the first and second lines of the non-locality/state/postcode portion of the address. | Unit 209, 274 Harbour Drive |
success
|
Boolean | Indicates if the request was successful or not. | true |
dpid
|
String | Australia Post delivery point identifier. | 99119187 |
lga_name
|
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
|
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
|
String | Government legal property description. | 10//SP9489 |
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. |
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. | 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. | 126021591 |
gnaf_id
|
String | The unique persistent identifier of the G-NAF address. | GANSW705051429 |
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. |
max |
Integer | The maximum number of results to return. A number between 1 and 100. The default is 10 results. |
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 |