Searching

Searches take two pieces of information: what and where. The what is what to search for, and can be a business name, type of business or an attribute of a business (such as '24-hour'). The where must be a location to search in.

Note: When building your application, we require you to provide "reporting events" relating to interactions with each business listing back to Sensis. This can be done very simply by following the Reporting Usage Events instructions.

The what to search for is specified by the query parameter, and the where to search is specified by the location parameter.

What

The what (ie, query parameter) is simply a series of words to search for. The search engine will attempt to find as many of the given words as possible in fields such as the name of the business, the listing category and various business information fields.

For example, a search for:

locksmith

will find matches for businesses with 'locksmith' in their name, as well as businesses in the category 'Locks & Locksmiths'.

See also: Search Query Tips

Where

The where (ie, location parameter) must contain a location to search in. Businesses closer to that location will be prioritised higher in the results. There are many ways to specify a location, such as by suburb name, by postcode or state.

It is important to note that the location parameter does not restrict search results. For example, if a good match is found outside the given region, it may be returned before a closer, but less-relevant, listing.

See also: Location Tips for ways to specify a location.

Search Parameters

The Search endpoint accepts the following parameters (in addition the Common Fields).

Name Type Description Remarks
query string What to search for. See Search Query Tips for details.
location string Location to search in. See Location Tips for details.
page number Page number to return. See Pagination for details.
rows number Number of listings to return per page. See Pagination for details.
sortBy string Listing sort order. See Sorting for details.
sensitiveCategories boolean Filtering potentially unsafe content. See Filtering Unsafe Content for details.
categoryId string Filter listings returned by category id See Category Filtering for details.
postcode string Filter listings returned by postcode See Postcode Filtering for details.
radius Double Filter listings returned to those within the radius distance of the location. See Radius Filtering for details.
locationTiers Integer Filter listings returned to those within a number of location tiers of the location. See Location Tier Filtering for details.

Search Response Fields

The Search endpoint returns a JSON response message that will look something like:

{
    "results": [
        {
            "businessName": "Hairdresser",
            "categories": [
                {
                    "name": "Hairdressers"
                }
            ],
            "primaryAddress": {
                "addressLine": "123 Main Street",
                ...
            }
            ...
        }
        ...
    ],
    ...
    "count": 20,
    "totalResults": 19791,
    "currentPage": 1,
    "totalPages": 990,
    "date": "2011-02-28T12:01:02.345+1000",
    "time": 10,
    "code": 200,
    "message": "OK"
    ...
}

The Search endpoint will return the following fields (in addition to the Common Fields):

Name Type Description Remarks
results array Returned listings Array of objects. See Listing Schema for details.
count number Number of listings returned on this page. See Pagination for details.
totalResults number Total number of listings found in the database. See Pagination for details.
currentPage number Current page number. See Pagination for details.
totalPages number Total number of pages. See Pagination for details.
executedQuery string The executed query. The query that was actually executed against the database. See Spell-Checker for details.
originalQuery string Original search query. Will always contain the value of the query input parameter. See Spell-Checker for details.

Note: During our beta phases, there may be duplicate listings for a single business, where that business is listed under multiple categories. This will be addressed for the final release of the API. Please check back here later, or see What's New for updates.

The Search endpoint returns listings in pages, with a default page size of 20. To request subsequent pages, increment the page input parameter. See Pagination for details.

Sometimes the search query may be adjusted by the search engine, in which case the executedQuery and originalQuery fields will be different. See Spell-Checker for more information.

For details on the structure of the results field, see Listing Schema.