Ad Availability API

Using this API you can check if the Server has ads available for the Country, it will return the provider value (INMOBI, GOOGLE etc) which should be used to request ads from the client directly.

URL:

appId – your appId assigned to your app

co – Country Code of the Client requesting for Ads

example:

Response:

String with the value, SERVER, GOOGLE/ADMOB, INMOBI etc

If the return value is SERVER then the client should use the Ad Request API below to request ads from the server, in any other case you should use the return value and use a local library (SDK) to request ads directly from the client.

Ad Request API

URL:

Input Parameters:

appId – your appId assigned to your app

query – query string for the ad requests

lat – current Latitude

lng – current Longitude

user – unique userid, it should be at least unique during a session

co – Country Code of the Client requesting for Ads

Response:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<searchResult>
  <listing>
    <action>click</action>
    <address>2358 Pico Blvd,Santa Monica,CA,90405</address>
    <category></category>
    <description>Color Copies and Posters -  Highest Quality at Great Prices -.</description>
    <distance>10.73112745884962</distance>
    <distanceToCenter>0.0</distanceToCenter>
    <lat>34.021653</lat>
    <listingType>PAID</listingType>
    <lng>-118.465419</lng>
    <map_url>http://maps.google.com/?q=2358 Pico Blvd,Santa Monica,CA,90405</map_url>
    <name>Super Fast Copying &amp; Binding Systems</name>
    <phone>4242299434</phone>
    <pid>1</pid>
    <pretty_distance>10.73</pretty_distance>
    <profile_display_url>www.superfastla.com</profile_display_url>
    <profile_url>http://local.xad.com/rest/redirect?k=SpryLogics411WS&amp;v=1.0&amp;l_id=2hd1XTG12%7Efcd1XTG12-0%7E1%7E1%7E1%7E1%7ECA%7Eus%7Efcd1XTG12%7E1%7E0%7E0%7E%7E0%7E0&amp;website=aHR0cDovL2NsaWNrcy5zdXBlcnBhZ2VzLmNvbS9jdC9jbGlja1Rocm91Z2g%2FU1JDPXZlLXBvcnRhbCZ0YXJnZXQ9U1AmUE49MSZUPVdlc3QrSG9sbHl3b29kJlM9Q0EmQz1wdWJsaXNoZXImUEdJRD1kYWxhczExMS44MDgzLjEzODE1MTQyMDgxMzMuOTUxMDg2MTIwMyZBTEc9MTExJlRTPWJ1bGxzJkFDVElPTj1sb2cscmVkJkxJRD0wMDE4MzczNTg2JlRSPTEmYmlkVHlwZT1DTElLJnJlbGF0aXZlUG9zaXRpb249MCZwb3NpdGlvbj0wJlBHU049RTAmTVQ9RCZESUQ9TnlwTnZUUzBlWkdhSzY4SHNPbFJZUSUzRCUzRCZhY2lkPVFPaDMyeWRIR0dRdUp2YWVRTmhFTVElM0QlM0QmY2lkPTE2NjA1NTQ3JmJpZD0wJkVNPTAmTURJRD1DRWJvMmlXaDM2TSUzRCZSUz0xLjA5Nzc2NzUmRkw9dXJsJlRMPW9mZiZMT0M9aHR0cDovL3N1cGVyZmFzdGxhLmlhcmJpei5jb20vb2liQk1VdmllNnM9&amp;t=website&amp;appid=thebest&amp;uid=peter</profile_url>
    <provider>xad</provider>
    <providerid>2hd1XTG12%7Efcd1XTG12-0%7E1%7E1%7E1%7E1%7ECA%7Eus%7Efcd1XTG12%7E1%7E0%7E0%7E%7E0%7E0</providerid>
    <rating>0.0</rating>
    <reporting>
      <url>http://local.xad.com/rest/notify?v=1.1&amp;k=Fo6VuJDKh_AzqkYthnGTIHapH3Km6bEPxi6NJWYbbXk.&amp;l_id=2hd1XTG12%7Efcd1XTG12-0%7E1%7E1%7E1%7E1%7ECA%7Eus%7Efcd1XTG12%7E1%7E0%7E0%7E%7E0%7E0&amp;t=${action}&amp;uid=peter&amp;ts=${timestamp}</url>
      <actions>
        <call>call</call>
        <click>click</click>
        <description>desc</description>
        <direction>direction</direction>
        <impression>imp</impression>
        <map>map</map>
        <review>review</review>
      </actions>
      <handleCookies>false</handleCookies>
    </reporting>
    <selected>0</selected>
    <sponsorsMessage>Sponsored by Superpages.com</sponsorsMessage>
    <votedByMe>false</votedByMe>
    <votedByOther>false</votedByOther>
  </listing>
  <listing>
    <action>click</action>
    <address>2358 Pico Blvd,Santa Monica,CA,90405</address>
    <category></category>
    <description>Superfast Copying &amp; Binding - Highest Quality at the lowest price.</description>
    <distance>10.73112745884962</distance>
    <distanceToCenter>0.0</distanceToCenter>
    <lat>34.021653</lat>
    <listingType>PAID</listingType>
    <lng>-118.465419</lng>
    <map_url>http://maps.google.com/?q=2358 Pico Blvd,Santa Monica,CA,90405</map_url>
    <name>Super Fast Copying &amp; Binding Systems</name>
    <phone>4246455817</phone>
    <pid>2</pid>
    <pretty_distance>10.73</pretty_distance>
    <profile_display_url>www.superfastla.com</profile_display_url>
    <profile_url>http://local.xad.com/rest/redirect?k=SpryLogics411WS&amp;v=1.0&amp;l_id=3hd1XTG12%7Efcd1XTG12-1%7E1%7E1%7E1%7E1%7ECA%7Eus%7Efcd1XTG12%7E1%7E0%7E1%7E%7E0%7E0&amp;website=aHR0cDovL2NsaWNrcy5zdXBlcnBhZ2VzLmNvbS9jdC9jbGlja1Rocm91Z2g%2FU1JDPXZlLXBvcnRhbCZ0YXJnZXQ9U1AmUE49MSZUPVdlc3QrSG9sbHl3b29kJlM9Q0EmQz1wdWJsaXNoZXImUEdJRD1kYWxhczExMS44MDgzLjEzODE1MTQyMDgxMzMuOTUxMDg2MTIwMyZBTEc9MTExJlRTPWJ1bGxzJkFDVElPTj1sb2cscmVkJkxJRD0wMDE4MzczNTg2JlRSPTEmYmlkVHlwZT1DTElLJnJlbGF0aXZlUG9zaXRpb249MSZwb3NpdGlvbj0xJlBHU049RTAmTVQ9RCZESUQ9TCUyQnhLS1N0dlh1S1phSEJGWjFwWEhRJTNEJTNEJmFjaWQ9UU9oMzJ5ZEhHR1F1SnZhZVFOaEVNUSUzRCUzRCZjaWQ9MTY2MDU1NTEmYmlkPTAmRU09MCZNRElEPTg1WEViZ0UlMkZlNUklM0QmUlM9MS4wOTc3Njc1JkZMPXVybCZUTD1vZmYmTE9DPWh0dHA6Ly9zdXBlcmZhc3RsYS5pYXJiaXouY29tL05sU3p3NXpwYnY4PQ%3D%3D&amp;t=website&amp;appid=thebest&amp;uid=peter</profile_url>
    <provider>xad</provider>
    <providerid>3hd1XTG12%7Efcd1XTG12-1%7E1%7E1%7E1%7E1%7ECA%7Eus%7Efcd1XTG12%7E1%7E0%7E1%7E%7E0%7E0</providerid>
    <rating>0.0</rating>
    <reporting>
      <url>http://local.xad.com/rest/notify?v=1.1&amp;k=Fo6VuJDKh_AzqkYthnGTIHapH3Km6bEPxi6NJWYbbXk.&amp;l_id=3hd1XTG12%7Efcd1XTG12-1%7E1%7E1%7E1%7E1%7ECA%7Eus%7Efcd1XTG12%7E1%7E0%7E1%7E%7E0%7E0&amp;t=${action}&amp;uid=peter&amp;ts=${timestamp}</url>
      <actions>
        <call>call</call>
        <click>click</click>
        <description>desc</description>
        <direction>direction</direction>
        <impression>imp</impression>
        <map>map</map>
        <review>review</review>
      </actions>
      <handleCookies>false</handleCookies>
    </reporting>
    <selected>0</selected>
    <sponsorsMessage>Sponsored by Superpages.com</sponsorsMessage>
    <votedByMe>false</votedByMe>
    <votedByOther>false</votedByOther>
  </listing>
  <user>peter</user>
</searchResult>

 

list of listing objects that should be used to render the ads

Listing object contains standard fields like name, description, phone number and address that should be used to render the ads, there are some additional parameters that need some extra attention:

action – possible values (url, click and call), if action is url, user should be directly taken to the URL provided by profile_url parameter when user click on the ad listing on the listing page. If action is click , user should be taken to a details page which can be rendered based on the information provided in the listing object. If action is call, a call should be made to the number provided by the phone parameter.

sponsorsMessage – the message provided by this field must be displayed above the as listings to indicate that the listings are sponsored.

Reporting

All the actions that user performs on the listing such as click, call, map directions etc must be reported by making an http call to the url provided in each listing object under the reporting section, below are the details

The reporting section in the response contains 3 main fields url and actions

url – this url is basically a template url with some place holders that must be replaced before url is invoked.

actions – provides all the possible actions that can be reported, appropriate value must be replaced in the above URL before making the call

handleCookies if true, you must save the cookie passed back in the response to the url, this cookie must be passed back in the following request to the reporting url.

 

Actions to be to reported:

impression – When the listing item is shown in the listing page (only call this URL is present, not required for all the add provider)

click – when listing item is clicked on (only call this URL is present, not required for all the add provider)

description – when the details of the listing are shown (usually after the click)

call – when user makes a call to the business listing (either from the listing page or from the details page)

map – when user views the map of the listing (if present)

directions – when the users view the directions to the listing address (if present)

 

Place Holder Replacement:

there can be several place holders in the url that must be replaced with appropriate values before making the call, the place holders are of the following format in the url: ${PLACE_HOLDER}, list of currently supported placeholders

- ${action} – must be replaced with appropriate action vale provided in the response

- ${timestamp} must be replaced with the timestamp (milliseconds since Jan 1, 1970) at the time of invocation