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/v1/<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.
geometry string Filter listings returned to those within a defined polygon. See Polygon 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).
updatedSince number / Joda time returns only those listings that have been updated since "updatedSince".  This parameter either takes in a number which is milliseconds since epoch or in the following Datetime format '2014-04-01T10:00:00.000Z'
newSince number / Joda time returns only those listings that are newly added since "newSince".  This parameter either takes in a number which is milliseconds since epoch or in the following Datetime format '2014-04-01T10:00:00.000Z'

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/v1/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.

POST Requests

It is also possible to use POST instead of GET to call the /search endpoint. This may be particularly useful for requests that use parameters that would otherwise be too large to fit in a GET request. To do this, POST to the /search endpoint with the request parmeters encoded as a simple JSON object string in the body of the request, as in this example:

{
 "query":"plumbers",
 "location":"melbourne",
 "key":"yourkey",
 "rows":"5",
 "page":"2",
 "productKeywords":["Concern:Leaks", "Type:Residential"]
}

Note that all params should be Strings or lists of Strings (for params which can have multiple values), even numeric-looking params such as "rows". The available params and the format of the results are the same as for GET requests.