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, so if you cannot report on any of these events, please contact us so we can agree an appropriate level of reporting for 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 POST request to the Report endpoint (see Report endpoint) for the event (see the Name column in the table above). (HTTP GET method is deprecated for report endpoints)

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 POST 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, your java code(sample) will look like:

 

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Arrays;
import java.util.List;

public class ReportClient {


    private void sendPost() throws Exception {

        String USER_AGENT = "Mozilla/5.0";
        String userIp = "192.1.2.3";
        String key = "secret"; // your api key
        String url = "http://api.sensis.com.au/v1/test/report/appearance";
        String sessionId="123467890";
        URL obj = new URL(url);
        HttpURLConnection con = (HttpURLConnection)obj.openConnection();

        //add reuqest header
        con.setRequestMethod("POST");
        con.setRequestProperty("User-Agent", USER_AGENT);
        con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");



        // can send multiple report ids in one request
        List<String> reportIds = Arrays.asList("VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIxMjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0");

        // Send post request
        con.setDoOutput(true);
        DataOutputStream wr = new DataOutputStream(con.getOutputStream());
        wr.writeBytes("userIp=" + userIp);
        wr.writeBytes("&");
        wr.writeBytes("key=" + key);
        wr.writeBytes("&");
        wr.writeBytes("userSessionId=" + sessionId);

        for (String reportId : reportIds) {
            wr.writeBytes("&");
            wr.writeBytes("id=");
            wr.writeBytes(reportId);
        }

        wr.flush();
        wr.close();

        int responseCode = con.getResponseCode();
        System.out.println("\nSending 'POST' request to URL : " + url);
        System.out.println("Response Code : " + responseCode);

        BufferedReader in = new BufferedReader(
                new InputStreamReader(con.getInputStream()));
        String inputLine;
        StringBuilder response = new StringBuilder();

        while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
        }
        in.close();
	con.disconnect();
        //print result
        System.out.println(response.toString());

    }

    public static  void main(String[] args) throws Exception {
        ReportClient client = new ReportClient();
        client.sendPost();

    }
}

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

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

If a user then selects to call the phone number, send an HTTP POST 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:

 

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Arrays;
import java.util.List;

public class ReportClient {

    private void sendPost() throws Exception {

        String USER_AGENT = "Mozilla/5.0";
        String userIp = "192.1.2.3";
        String key = "secret"; // your api key
        String url = "http://api.sensis.com.au/v1/test/report/dial";
        String sessionId="123467890";
        String content="(03)12345678";
        URL obj = new URL(url);
        HttpURLConnection con = (HttpURLConnection)obj.openConnection();

        //add reuqest header
        con.setRequestMethod("POST");
        con.setRequestProperty("User-Agent", USER_AGENT);
        con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");



        // can send multiple report ids in one request
        List<String> reportIds = Arrays.asList("VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIxMjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0");

        // Send post request
        con.setDoOutput(true);
        DataOutputStream wr = new DataOutputStream(con.getOutputStream());
        wr.writeBytes("userIp=" + userIp);
        wr.writeBytes("&");
        wr.writeBytes("key=" + key);
        wr.writeBytes("&");
        wr.writeBytes("userSessionId=" + sessionId);
        wr.writeBytes("&");
        wr.writeBytes("content=" + content);

        for (String reportId : reportIds) {
            wr.writeBytes("&");
            wr.writeBytes("id=");
            wr.writeBytes(reportId);
        }

        wr.flush();
        wr.close();

        int responseCode = con.getResponseCode();
        System.out.println("\nSending 'POST' request to URL : " + url);
        System.out.println("Response Code : " + responseCode);

        BufferedReader in = new BufferedReader(
                new InputStreamReader(con.getInputStream()));
        String inputLine;
        StringBuilder response = new StringBuilder();

        while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
        }
        in.close();
	con.disconnect();
         //print result
        System.out.println(response.toString());

    }

    public  static  void main(String[] args) throws Exception {
        ReportClient client = new ReportClient();
        client.sendPost();

    }
}

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"
}