Get by Listing ID

The Get by Listing ID endpoint returns a single listing given its unique ID. It will return between zero and one result. A listing's unique ID can be discovered by performing a search, and grabbing the value of the id field. This endpoint can be used to implement a 'details' page or a 'bookmarking' feature.

Usage

http://api.sensis.com.au/ob-20110511/<env>/getByListingId?key=<key>&query=<id>

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

Parameters

The Get By Listing ID endpoint takes the following parameters:

Name Type Description Remarks
key string API key (required) See Authenticating for details.
query string Unique ID of the listing to return (required) This is the id field of the listing. See Listing Schema for details.
includeReviews boolean true or false A value of true will mean the response will contain the reviewSummaries and maximum of 10 reviews in the response. See Listing Schema for details.
includePois boolean true or false A value of true will mean the response will contain up to a maximum of 10 points of interest (Eg. railway stations, car parks, ATMs) in the response. See Listing Schema for details.
categoryId string Filter included points of interest (Eg. railway stations, car parks, ATMs) returned by category id See POI Category Filtering for details.

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 containing at most one listing. See Listing Schema for details.
count number Number of listings returned on this page. Will be either zero or one for this endpoint.
totalResults number Total number of listings found in the database. Will be either zero or one for this endpoint.
executedQuery string The executed query. Will always contain the value of the query input parameter.
originalQuery string Original search query. Will always contain the value of the query input parameter.
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).

See also: Searching for more information on these fields.

Note: Spell-checking, pagination and location searching do not apply to this endpoint.

Result

HTTP Status

The Get by Listing ID 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 request was successful. Note that this does not mean that the listing was actually found. For this purpose, check the count property.
400 Validation error Invalid or missing input parameters were given. See Validation Errors.

Example

To fetch the listing with ID 999 (remembered from a previous search), assuming your API key was secret:

http://api.sensis.com.au/ob-20110511/test/getByListingID?key=secret&query=999

This should return a JSON response that looks similar to:

{
    "results": [
        {
            "businessId": "999",
            "businessName": "Hairdresser",
            "categories": [
                {
                    "name": "Hairdressers"
                }
            ],
            "primaryAddress": {
                "addressLine": "123 Fitzroy Street",
            },
            ...
        }
    ],
    "count": 1,
    "totalResults": 1,
    "executedQuery": "999",
    "originalQuery": "999",
    "date": "2011-02-28T12:01:02.345+1000",
    "time": 10,
    "code": 200,
    "message": "OK"
}

To fetch the listing above with reviews use

http://api.sensis.com.au/ob-20110511/test/getByListingID?key=secret&query=999&includeReviews=true

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

version 7 as of 6 months ago by Thinh Nguyen