Suggest oneSearch

The suggest/oneSearch endpoint returns completed query suggestions that match the query string provided. Auto-suggestion typically provides likely matches to the text that has been entered by the user. This can be a useful feature as it reduces the number of spelling errors entered, enables the user to enter fewer keystrokes and also exposes possible alternatives that the user may not have recalled unaided.

It is possible to specify the type(s) and/or sub-type(s) of suggestions to be returned. It is also possible to specify the number of suggestions to return and to boost suggestions that are located with a geo-coded bounding box

Query entered:

carpen… 

Suggestions returned:

Carpenter Rocks SA 5291 Carpenters Carpenter carpenters joiners carpenter ford etc. etc

As can be seen, a range of suggestions can be returned, from a town, a business types, and even a business name.

Usage

http://api.sensis.com.au/v1/<env>/suggest/oneSearch?key=<key>&query=<query>

Where env is the id of the environment to send the request to. Can be either test or prod.

The list of suggestions that is returned can be configured by a number of parameters. The parameters allow the request to boost suggestions from a particular geographic area, to select particular types of suggestions and to limit the number of suggestions returned.

It is important to note that oneSearch MUST be entered with that same case. onesearch, ONESEARCH, or OneSearch will not work

Parameters

The suggest/oneSeacrh endpoint takes the following parameters:

NameTypeDescriptionRemarks

key

string

API key (required)

See Authenticating for details.

query

string

The query term used for matching to potential suggestions (required)

See Suggest query for details.

location

series of four comma separated geo-codes

Describes top left latitude and longitude and bottom right latitude and longitude of a geographic bounding box used to boost the ordering of suggestions that fall within a specified area of interest 

See suggestOneSearch location boost parameter for more details

type

UPPERCASE string or series of comma separated uppercase strings

Allows user to select what type of suggestion(s) will be returned. Valid values of type are: 
ADDRESS
BUSINESS
NON_BUSINESS_POI

ADDRESS covers a number of levels of address
BUSIENSS covers both BUSINESS_NAME and BUSINESS_TYPE suggestions
NON_BUSINESS_POI covers forty types of points of interest

For more information, please see TYPE and SUBTYPE

NOTE In order to use the subtype parameter, you do not have to specify the corresponding type parameter that is the parent type of the subtype. See more details below under subtype

subType

Uppercase string or series of comma separated uppercase strings 

After a value or values have been provided for the type parameter, it is possible to specify one or more subtype values to further limit the suggestions to particular subtypes of suggestion. 

 

For the various examples, of subtypes, please see SUBTYPE below.You don’t have to specify a TYPE to filter by SUBTYPE – they are independent of each other.

rows

number

Number of suggestions to return

The absolute maximum number of suggestions that can be returned is 100.

Suggest Query

The data sources used to provide suggestions to match the query cover seven common types of a search query terms:

  • location (address) from the WhereIs ® database
  • business type from Yellow Pages data
  • business type with location from Yellow Pages® data
  • business names from Yellow Pages®and White Pages™ data
  • business names with location from Yellow Pages®and White Pages™ data
  • points-of-interest categories from the WhereIs ® database
  • points-of-interest with location from the WhereIs ® database

TYPE and SUBTYPE examples

Examples of typical suggestions that will be returned for different TYPE and SUBTYPE parameters for particular example queries are displayed in the table below:

TYPE SUBTYPE Example Query Example Suggestion

ADDRESS

state vi.. Victoria
region mornington pen..
Mornington Peninsula, VIC
suburb mel.. Melbourne VIC 3000
beau.. Beaumaris VIC 3193
warn.. Warrnambool VIC 3280
street morey beau.. Morey Street, Beaumaris, VIC 3193
9 morey beau.. 9 Morey Street, Beaumaris, VIC 3193
9A morey beau.. 9A Morey Street, Beaumaris, VIC 3913          
Unit 9A morey beau.. Unit 9A Morey Street, Beaumaris, VIC 3913
intersection morey wood.. corner of Morey Street and Wood Street, Beaumaris, VIC 3193

BUSINESS

business_name bunn.. Bunnings Warehouse
bunnings men.. Bunnings Warehouse near Mentone VIC 3194
business_type hardwa… hardware stores
hardware men.. hardware stores near Mentone VIC 3194
NON_BUSINESS_ POIS Kyne.. Kyneton District Health Service
Kyneton Station
Kyneton Police Station
ATMS atm beaum.. CBA ATM - Beaumaris
PUBLIC_PHONE payphone Telstra Payphone
HOSPITAL_POLYCLINIC Sand.. Sandringham Hospital
PLACES_OF_INTEREST Hist.. Adelaide Gaol Historic Site
SPORTING_VENUES Mel… Melbourne Park
CLUBS social Bellavista Social Club
CAR_PARKS Beau… Car Park - Beaumaris Carpark
PICNIC_AREAS Yarra.. Yarrambat Picnic Area

CHURCHES_OTHER_PLACES_
OF_WORSHIP

st and

St Andrews Cathedral

FIRE_STATIONS Belg… Belgrave Fire Station
TOILETS Dock.. Public Toilet - Docklands Park

NURSING_HOMES_
RETIREMENT_COMMUNITIES

Greek… Greek Community Hostel for the Aged
TERTIARY_OTHER_INSTITUTIONS Deak.. Deakin University Geelong Waterfront Campus
SWIMMING_POOLS Mel.. Melbourne Sports & Aquatic Centre
LIBRARIES Carl.. Carlingford Library
LICENSING_CENTRES Syd.. RTA Motor Registry North Sydney
AMBULANCE_STATIONS Men.. Menai Ambulance Station
NRMA_BRANCH_OFFICES Syd.. NRMA - North Sydney        
PARKS_RESERVES Bot.. The Botanic Park
BOAT_RAMPS Fran… Boat Ramp - Frankston
RACECOURSES_TROTTING_TRACKS Fl… Flemington Racecourse
LOCAL_GOVERNMENT_OFFICES Bay.. Bayside City Council
LOOKOUTS Gen.. Genoa Peak Lookout
BAYS_BEACHES_ETC Drom.. Dromana Beach
RAILWAY_STATIONS So… Southern Cross Station
COURTS_COURTHOUSES Fra.. Frankston Magistrates Court
COACH_TERMINALS Ben.. Benalla ANZ Coach Stop ONR

SCHOOLS_COLLEGES
PRIVATE_PUBLIC

Brig.. Brighton Primary School

POST_OFFICES

So.. South Melbourne Postal Business Centre
POLICE_STATIONS St k.. St Kilda Road Police Station
INFORMATION_CENTRES Bena.. Benalla Visitor Information Centre
CEMETERIES_CREMATORIA Bright c.. Bright Cemetery

ELECTRIC_VEHICLE_CHARGER
_POINT

Or.. Origin ChargePoint
TENPIN_BOWLING Su.. Surfers Paradise Tenpin

GOLF_COURSES_CLUBS_
DRIVING_RANGES

Barnb.. Barnbougle Dunes Golf Links
CAMPING_AREAS Fli.. Flinders Beach Camping Area

CARAVAN_TOURIST_MOBILE
_HOME_PARKS

Da.. Nrma Darlington Beach Holiday Park
AIRPORTS_AND_AIRFIELDS Tu.. Melbourne Tullamarine Jetstar Domestic Departures
REST_AREA Blu.. Blue Mountain Northbound Truck Stop
WHARVES_MARINAS Abel.. Meridien Marinas Abel Point

suggest/oneSearch Location boost parameter

You can boost suggestions within the ordering of suggestions for suggestions from local areas with the suggest/oneSearch endpoint by using the location parameter.  The location parameter describes a bounding box (which is a set of four geo-codes). Any matching suggestions that have a geo-code address within that bounding box or a centre point within the bounding box will be boosted in the ordering of the suggestions returned.

When specifying the location to boost for, you need to supply the following in order, separated by commas:

  • Top left latitude value
  • Top left longitude value
  • Bottom right latitude value
  • Bottom right longitude value

Examples

Basic Suggest

http://api.sensis.com.au/v1/test/suggest/oneSearch?key=<key>&query=ston

This returns a simple list of mixed suggestions 

{

  • results
    [
    • {
      • value"Stony Creek QLD 4514",
      • type"ADDRESS",
      • subType"SUBURB"
      },
    • {
      • value"Stonelands QLD 4612",
      • type"ADDRESS",
      • subType"SUBURB"
      },
    • {
      • value"Stonehenge QLD 4357",
      • type"ADDRESS",
      • subType"SUBURB"
      },
    • {
      • value"Upper Stone QLD 4850",
      • type"ADDRESS",
      • subType"SUBURB"
      },

...

Type and Subtype filtering

Restricting the query to type business will only return BUSINESS_NAME and BUSINESS_TYPE suggestions

http://api.sensis.com.au/v1/test/suggest/oneSearch?key=<key>&type=BUSINESS&query=ston

 

{

  • results
    [
    • {
      • value"stone mason",
      • type"BUSINESS",
      • subType"BUSINESS_TYPE"
      },
    • {
      • value"stone",
      • type"BUSINESS",
      • subType"BUSINESS_TYPE"
      },
    • {
      • value"Abbeyfield Society (L'ston) Incorp",
      • type"BUSINESS",
      • subType"BUSINESS_NAME"
      },
    • {
      • value"stone italia",
      • type"BUSINESS",
      • subType"BUSINESS_NAME"
      },

 

To refine the query further using a subtype, we just need to specify which subtype we're interested in. Again, please not we have to specify subType in that exact formatting

http://api.sensis.com.au/v1/test/suggest/oneSearch?key=<key>&subType=BUSINESS_NAME&query=ston

{

  • results
    [
    • {
      • value"Abbeyfield Society (L'ston) Incorp",
      • type"BUSINESS",
      • subType"BUSINESS_NAME"
      },
    • {
      • value"stone italia",
      • type"BUSINESS",
      • subType"BUSINESS_NAME"
      },
    • {
      • value"stonegrill",
      • type"BUSINESS",
      • subType"BUSINESS_NAME"
      },
    • {
      • value"blue stone",
      • type"BUSINESS",
      • subType"BUSINESS_NAME"
      },

 

Location Boost

Without a location boost the search term:

cow

will produce these suggested matches:

Cow Bay QLD 4873
Cow Flat NSW 2795
Cowes VIC 3922
Cowa VIC 3862
etc etc...


If the location bounding box for Cowra NSW is introduced:

http://api.sensis.com.au/v1/test/suggest/oneSearch?query=&location=-33.618228,148.065451,-34.12301,149.203428&key=...


…then the suggested matches will show Cowra NSW at the top of the list:

Cowra NSW 2749
Cow Bay QLD 4873
Cow Flat NSW 2795
etc


The location boost applies to any results that are association with a geo-code address that falls in the specified bounding box or that have a centre point that falls in the bounding box.

Note that the boost only applies to suggestions that are within the bounding box. Suggestions for geo-codes that are in close proximity to the bounding box but not actually within the bounding box receive no boost at all

Response Message

HTTP content type: application/json

The response message is a JSON object containing the "suggestions"  – with three fields for each suggestion:

  • value (the suggestion)
  • type
  • subtype

Here's an example of a sample response message:

{
  "results":[

{ "value": "Carpenter Rocks SA 5291", "type": "ADDRESS", "subType": "SUBURB"}, {"value": "carpenters", "type": "BUSINESS", "subType": "BUSINESS_TYPE" }, { "value": "Carpenter", "type": "BUSINESS", "subType": "BUSINESS_NAME" }, { "value": "carpenters, joiners", "type": "BUSINESS", "subType": "BUSINESS_TYPE" }, { "value": "carpenter ford", "type": "BUSINESS", "subType": "BUSINESS_NAME" } ], "code": 200, "date": "2013-12-06T10:48:38.168+1100", "time": 273, "message": "Ok" }

HTTP Status

The Search endpoint will always return HTTP 200 on success. See HTTP Status Codes for possible error codes.

Status Codes

The following status codes can be returned in the code field:

CodeDescriptionRemarks
200 Success The search was successful.
400 Validation error Invalid or missing input parameters given. See Validation Errors.

Frequently asked questions

Within each type or subtype of suggestion, how is the ordering of suggestions decided?

The suggestions are ordered according to usage data that indicates how frequently they were entered in appropriate web sites. For example, the ADDRESS suggestions and NON_BUSINESS_POI suggestions are ordered by their frequency within searches on the WhereIs™ website and apps. Business type suggestions are ordered by their frequency on the Yellow Pages® website and apps. Business name suggestions are ordered by their frequency on the Yellow Pages® and White Pages ™ websites and apps.

How are suggestions ordered across different types of suggestion?

Some simple rules have been applied for the default ordering of suggestions when all types of suggestions are requested (that is, when no TYPE or SUBTYPE parameters are specified).

Generally larger ADDRESS suggestions come first (STATE, REGION & SUBURB). Certain important types of points-of-interest such as AIRPORTS_AND_AIRFIELDS then follow. BUSINESS_TYPE suggestions follow and they are generally followed by BUSINESS_NAME suggestions.

If I don’t like the way the suggestions are ordered, can I get them in a customised order?

It is currently not possible to change the ordering of the suggestions returned. One possibility is to change the order programmatically after they have been returned and then present the suggestions to the end user. For example you might want to do separate calls to get the top three addresses, top three POIs, top three business types and top three business names and then present all twelve suggestions to the user in a customised manner.