One Search

The One Search endpoint allows both the "what" and "where" parts of a query to be specified in a single parameter. It automatically splits this query into its respective "what" and "where" components. The "what" is interpreted as either a business type or name, and the "where" is used as the search location.

The "where" component can accept the following types of locations:

Location TypeDescriptionExample
Property address A property address '123 Lonsdale St, Melbourne'

Street name

A street name optionally within a suburb

'Lonsdale St, Melbourne'
Suburb or Locality

Name of a suburb or locality

'Glen Waverley'

Postcode

Numerical postcode

'3150'

State or Territory       

Name of a state or territory

'VIC' or 'Victoria'

Unlike the normal SAPI Search, OneSearch does NOT support "what-less" or reverse search. If the query does not resolve to any "what" component, OneSearch will NOT return any listing in the results field. Instead, it will only return the meta-data of the "where" component as a bestLocation field and optionally the  alternativeLocations field (see below).

For example: the query "cafes melbourne" will be split into "what" being "cafes" and "where" being "melbourne".

In certain circumstances when the "what" and "where" are ambiguous, "join words" can be used to separate the "what" from the "where". For example, "cafes hardware melbourne" is interpreted as "what" being "cafes hardware" and "where" being "melbourne". By adding the join word "near", "cafes near hardware melbourne" is interpreted as "what" being "cafes" and "where" being "hardware melbourne" (there is a Hardware Street in Melbourne CBD).

The list of valid join words is:

  • near
  • nearby
  • on
  • around
  • in
  • at

Usage

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

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

Parameters

The One Search endpoint accepts most of the parameters that the normal Search accepts, with the following differences:

Name Type Description
query string Combinations of "what" or "where", either of which are optional, and can optionally be separated by a join word. (required)

boundingBox

string

Bounding box to serve as a hint to disambiguate the "what" within the query, E.g. "richmond" exists in several states, so if the bounding box is in Victoria, then it is interpreted as "Richmond Vic". However, if the query does not contain a "where" part, the centre of the boundingBox is used as the search location.

location  

string

Your CURRENT location as latitude,longitude, e.g. -37.7833,144.9667. It serves only as a hint to disambiguate the "what" within the query if the boundingBox is not provided. E.g. "richmond" exists in several states. So if your current location is in Victoria, then it is interpreted as "Richmond Vic". Note that unlike the boundingBox, this is never used to derive the search location.

sortBy  

string

Within a query this parameter is applied to, a resolveable Location Type must be established inorder to bring back appropriate results, otherwise it will look for a location from the string inputted.

radius       

-

As long as the query contains a resolvable location, radius will allow you to set the distance (in kilometres) to be searched surrounding the original location. 

hint string

This parameter only applies if you have a boundingBox, and no location specified in the query string. When “&hint=PLACE” it will provide a strict search for listings within the boundingBox specified, rather than filter on that location.

 

It also takes a new parameter:

NameTypeDescription
mappable boolean A value of true means that only listings with geocode granularity of PROPERTY or INTERSECTION will be returned. This means that these listings can be reliably used by mapping or geographical applications.

Response Message

HTTP content type: application/json

The response message is a JSON object containing the "results" field just like the Search endpoint. In addition, it also contains a "bestLocation" field with metadata describing the resolved location.

Example "bestLocation" that describes "melbourne":

 

bestLocation": {
    "approximated": false,
    "coordinates": {
        "centre": {
            "latitude": -37.813389,
            "longitude": 144.962832
        },
        "street": {
            "latitude": -37.813389,
            "longitude": 144.962832
        },
        "boundingBox": {
            "left": 144.951435521,
            "top": -37.799406981,
            "right": 144.976525454,
            "bottom": -37.823099254
        }
    },
    "granularity": "SUBURB",
    "postcode": "3000",
    "regions": [
        "GREATER MELBOURNE",
        "MELBOURNE - INNER CITY SUBURBS",
        "MELBOURNE CBD",
        "MELBOURNE COUNCIL"
    ],
    "state": "VIC",
    "suburb": "MELBOURNE",
    "suburbVanities": [
        "MELB"
    ]
}

If the "where" part within the query can be interpreted as more than one possible location, then the response message also contains an "alternativeLocations" field. This is a list of other locations, each having the same structure as the "bestLocation" field.


Result

HTTP Status

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

Please Note: We are no longer providing suggestion service for the oneSearch endpoint. If you require this service, please contact us and discuss options.