Search

The Search endpoint is the primary search endpoint. It takes a query and a location parameter to specify the words to search for and the location to search in. The Search endpoint automatically determines the intent of your search, ie, whether or not you're searching for the name or type of a business (or both).

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.

See also: Searching for more information.

Usage

http://api.sensis.com.au/ob-20110511/<env>/search?key=<key>&query=<query>&location=<location>[...]

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

Parameters

The Search endpoint takes the following parameters:

Name	Type	Description	Remarks
`key`	string	API key (required)	See Authenticating for details.
`query`	string	What to search for *(required unless location* is given)**	See Search Query Tips for details.
`location`	string	Location to search in *(required unless query* is given)**	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`	number	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.
`suburb`	string	Filter listings returned to those within the given suburb. Repeat the parameter to include multiple suburbs in the filter.	See Suburb Filtering for details.
`state`	string	Filter listings returned to those within the given state. Repeat the parameter to include multiple states in the filter.	See State Filtering for details.
`boundingBox`	string	Filter listings returned to those within a bounding box.	See Bounding Box Filtering for details.
`content`	string	Filter listings returned to only those with certain types of content.	See Filtering by Content Type for details.
`productKeyword`	string	Filter listings returned to only those containing certain product keywords.	See Filtering by Product Keyword for details.
`includePois`	boolean	A value of true will mean the response will include any relevant points of interest (Eg. railway stations, car parks, ATMs).

Response Message

HTTP content type: application/json

The response message is a JSON object containing the following members.

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.
`validationErrors`	array	Validation error messages (if any).	Returns an array of strings, one message per array item.
`date`	string	Date and time according to the server.	For example: `2011-02-28T12:01:02.345+1000`.
`time`	number	Time taken to process the request.	Reported in milliseconds.
`code`	number	Response code.	Indicates success, failure or partial success (see below).
`message`	string	Response message.	Contains an error message (if any).

Result

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:

Code	Description	Remarks
`200`	Success	The search was successful.
`206`	Search was modified	The spell-checker was run because the entered query returned no results (see Spell-Checker).
`400`	Validation error	Invalid or missing input parameters given. See Validation Errors.

Example

To search for a hairdresser in the 'St Kilda' area you could execute (assuming your API key was secret):

http://api.sensis.com.au/ob-201105111/test/search?key=secret&query=hairdresser&location=St+Kilda

This should return a JSON response that looks similar to:

{
            "results": [
                {
                    "id": "999",
                    "name": "Bob's Hairdresser",
                    "categories": [
                        {
                            "name": "Hairdressers"
                        }
                    ],
                    "primaryAddress" {
                        "addressLine": "123 Fitzroy Street",
                        ...
                    }
                    ...
                }
                ...
            ],
            ...
            "count": 20,
            "totalResults": 19791,
            "executedQuery": "hairdresser",
            "originalQuery": "hairdresser",
            "date": "2011-02-28T12:01:02.345+1000",
            "time": 10,
            "code": 200,
            "message": "OK"
        }

See also: Examples for how to call endpoints from code.

version 14 as of 3 months ago by Andrew Callaghan