Reporting Usage Events

When using SAPI, we require that you send us information about certain usage 'events'. These events are primarily based around "generating leads" for participating businesses. For example, we want to know when a user of your application views the details of a business listing or selects to visit a business's website. We only ask that you provide us with events related to business information sourced from our API.

Event Types

Below is a list of all the event types that we ask to be captured. We understand that not all of these will be relevant in all cases, and only ask that you report on events that are applicable to the features of your application.

Description	Name	Remarks
Add to Contacts	addToContacts	When a user adds a business's details to their contacts/address book.
Add to Favourites	addToFavourites	When a user bookmarks the web address in their browser, or saves the business to a 'favourites' list.
Appearance	appearance	When a business listings details (ie, business name & address and/or phone number) is displayed to a user.
Click to Call	dial	When a user selects a function to dial the business's phone number.
Get Directions	getDirections	When a user selects a function to view driving directions to the business from a location.
Print Business Details Page	printBusinessDetails	When a user prints the business listing details.
Send Email	sendEmail	When a user selects to write an email to the business.
Send to Friend	sendToFriend	When a user selects to share the business details with friend, such as via email or SMS.
Send to Mobile	sendToMobile	When a user selects to send the business details to their mobile phone.
View Business Details Page	viewDetails	When a user selects to view detailed business information (ie, more details than what is displayed for a business listing appearance). This event should not be used when a user clicks through to the business details page on yellowpages.com.au, as this event will already be identified by our website.
View Map	viewMap	When a user selects to view the business location on a map (use the Get Directions event instead if the map contains driving directions).
Website Referral	viewWebsite	When a user selects to visit the business's website.
View External Link	viewExternalLink	When a user selects to view one of the business's external links (ie, links returned in the externalLinks field. See Listing Schema).
View YouTube Video	viewVideo	When a user selects to watch a linked YouTube video (ie, any external link of type VIDEO. See Listing Schema).
Write Review	writeReview	When a user writes a review about the business.

Of course, your application may pioneer new events that are not listed above – in fact, we may not have even thought of them. If this is the case, please contact us to discuss ways we can set-up new events for you to provide this important "lead generation" information.

How to Report Events

Sending event notifications to us is quite simple. Within each search result there is a reportingId field associated with each business listing (see Listing Schema). All you need to do to fire the event is send a single HTTP GET request to the Report endpoint (see Report endpoint) for the event (see the Name column in the table above).

The following events require a content parameter to be specified:

Description	Name	Required content
Click to Call	dial	The content parameter specifies the phone number from the value field of the contact.
Send Email	sendEmail	The content parameter specifies the email address from the value field of the contact.
Website Referral	viewWebsite	The content parameter specifies the URL from the value field of the contact.
View External Link	viewExternalLink	The content parameter specifies the url field from the external link.
View YouTube Video	viewVideo	The content parameter specifies the url field from the external link.

Note: For event types that require the content parameter (ie, the events listed above) you cannot specify multiple reporting IDs per request.

Example

For example, given the following search result:

{
    "results": [
        {
            "name":"Bob's Hairdresser",
            ...
            "reportingId":"VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIx ⤶
MjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0",
            ...
            "primaryContacts": [
                {
                    "value":"(03) 1234 5678",
                    "type":"PHONE"
                }
            ],
            ...
        }
        ...
    ],
    ...
}

If a user searches for hairdressers and one of results displayed to the user is 'Bob's Hairdresser', then all you have to do is send an HTTP GET request to the report endpoint for an appearance event (see Report endpoint).

Given that:

• the user has an IP address of 192.1.2.3
• the user is accessing your application using a Mozilla Firefox browser
• the user has a session id with your application of 123467890
• your API key is secret

To report an appearance event for the above listing, you could execute:

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

This request should return a JSON response message that will look something like:

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

If a user then selects to call the phone number, send an HTTP GET request to the report endpoint for an dial event (see Report endpoint).

Given that:

• the user has an IP address of 192.1.2.3
• the user is accessing your application using a Mozilla Firefox browser
• the user has a session id with your application of 123467890
• your API key is secret
• the phone number dialled is (03) 1234 5678

To report a dial event for the above listing, you could execute:

http://api.sensis.com.au/ob-20110511/test/report/dial?key=<secret>&content=(03)%201234%205678&userIp=192.1.2.3&userAgent=Mozilla%20Firefox&userSessionId=123467890&id=VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIxMjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0

This request should return a JSON response message that will look something like:

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