Report

The Report endpoint is provided to allow API users to send "report events" relating to interactions with each business listing back to Sensis. It takes userIp, userAgent, userSessionId and id parameters to provide information associated with each reporting event.

See also: Reporting Usage Events for more information.

Usage

Single listing

http://api.sensis.com.au/ob-20110511/<env>/report/<eventName>?key=<key>&userIp=<userIp>&userAgent=<userAgent>&userSessionId=<userSessionId>&id=<id>&content=<content>

Multiple listings

http://api.sensis.com.au/ob-20110511/<env>/report/<eventName>?key=<key>&userIp=<userIp>&userAgent=<userAgent>&userSessionId=<userSessionId>&id=<id1>&id=<id2>&id=<id3>[...]

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

Note: A list of valid eventName values are listed in the Name column on the Event Types table at Reporting Usage Events.

Parameters

The Report endpoint takes the following parameters:

Name	Type	Description	Remarks
key	string	API key (required)	See Authenticating for details.
userIp	string	IP address of user accessing your application (required)	See Reporting Usage Events for details.
id	string	reportingId of listing associated with event (required)	The reportingId field provided in each listing returned in a search response. Multiple id parameters can be added where the same event applies to each listing, except where the content parameter is specified. See Reporting Usage Events for details.
userAgent	string	User agent of user accessing your application	For example, from the user-agent HTTP header. See Reporting Usage Events for details.
userSessionId	string	Session id of user accessing your application	See Note below.
content	string	Specific content to which the event applies (required)	Only required for certain events. See Reporting Usage Events for details.

Note: We request that you provide the userSessionId so that we can track a user's interaction with your application. It does not have to be the actual session id per se. For example, you may provide a derived value such as a hash of session id. This would be acceptable so long as a user's interaction with your application can be identified.

Response Message

HTTP content type: application/json

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

Name	Type	Description	Remarks
validationErrors	array	Validation error messages (if any).	Returns an array of strings, one message per array item.
validationWarnings	array	Validation warning 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 Report 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 report event was successful.
206	The report event contained validation errors	May occur where some of the id parameters sent are invalid. Successful report events will only be captured for the valid id(s).
400	Validation error	Invalid or missing input parameters given. See Validation Errors.

Example

Given a search from the api returns a response with the following listings:

{
    "results": [
        {
            "id": "999",
            "name": "Bob's Hairdresser",
            "categories": [
                {
                    "name": "Hairdressers"
                }
            ],
            "reportingId":"VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIx ⤶
MjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0",
            ...
        }, 
        {
            "id": "1000",
            "name": "Jill's Hairdresser",
            "categories": [
                {
                    "name": "Hairdressers"
                }
            ],
            "reportingId":"eyJib29rSWQiOiJTMDBXIiwibGlzdGluZ05hbW ⤶
UiOiJzdWJzY3JpYmVyTmFtZSIsInNvdXJjZSI6",
            ...
        }
        ...
    ],
    ...
    "count": 20,
    "totalResults": 19791,
    "executedQuery": "hairdresser",
    "originalQuery": "hairdresser",
    "date": "2011-02-28T12:01:02.345+1000",
    "time": 10,
    "code": 200,
    "message": "OK"
}

To report an appearance event for the listing with id 999, you could execute (assuming your API key was secret):

http://api.sensis.com.au/ob-20110511/test/report/appearance?key=<secret>&userIp=192.1.2.3&userAgent=Mozilla%20Firefox&userSessionId=123467890&id=VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIxMjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0

To report an appearance event for multiple listings, you could execute the following with the reporting id for each listing (assuming your API key was secret):

http://api.sensis.com.au/ob-20110511/test/report/appearance?key=<secret>&userIp=192.1.2.3&userAgent=Mozilla%20Firefox&userSessionId=123467890&id=VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIxMjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0&id=eyJib29rSWQiOiJTMDBXIiwibGlzdGluZ05hbWUiOiJzdWJzY3JpYmVyTmFtZSIsInNvdXJjZSI6

These requests should return a JSON response that looks similar to:

{
    "date": "2011-02-28T12:01:02.345+1000",
    "time": 10,
    "code": 200,
    "message": "OK"
}

See also: Reporting Usage Events for a list of all events which can be reported.

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