Promotion API

From api.bview.com

Jump to: navigation, search

Contents

Introduction

The intention of the BView Promotion API is to allow third parties to find and display promotions from the BView platform. Similarly the intention of the BView Content API is to allow third parties to find more information about BView listings. Results from listing searches will be returned in XML, allowing easy integration into third party sites.

They are stateless APIs which use simple GET requests and require an authentication key. All responses are XML documents. Please contact colin@bview.com if you do not have a key. Terminology The terms voucher and promotion are used interchangeably in this document to refer to special offers available on BView. They have either been added to BView by us or by the business owners themselves. The following types of promotions exist:

  • Affiliate Voucher: A promotional code for a particular offer on an external website.
  • Affiliate Sale: A general sale on a third party website.
  • Affiliate Deal: A particular deal on a third party website.
  • External Voucher: A link to an offer on a third party website.
  • SME Voucher: A voucher added to a BView business which is redeemed manually and is displayed on the BView site (i.e. no third party links).
  • SME Sale: A general sale added to a BView business which is displayed just on the BView site (i.e. no third party links).
  • SME Deal: A particular deal added to a BView business which is displayed just on the BView site (i.e. no third party links).
  • VAC discount: Promotions, associated with VAC discount cards.
  • LiveBookings offer: Integrated restaurant offers from http://www.livebookings.co.uk.
  • 5pm offer: Integrated restaurant offers from http://www.5pm.co.uk.
  • TopTable offer: Integrated restaurant offers from http://www.toptable.co.uk .

LiveBookings and TopTable vouchers returned from the API, include links through to the easy-to-use BView online restaurant booking form, compatible for display via an Apple iPhone application, or standard web site page.

Promotions may belong to either a particular listing (business) on BView, or to a group of listings. In practice this should make no difference to how the API operates and is used.

URL

The promotion API will be accessible through the following URL: http://www.bview.co.uk/app/frontend/PromotionApi<QUERY-STRING>

Query Parameters

Parameter name Required Possible values Value description Description
key Yes Your unique API key given to you by BView.
q optional recent returns recent vouchers It should be noted if used, all other parameters will be ignored in the results.
popular returns popular vouchers
what One of what and where is required Any text. See section 1.2 below for possible values.
whatType optional 0 Match ‘what’ search term against business names, categories, and voucher text. Determines how the ‘what’ search term will be applied in matching vouchers within the BView database. The default is 0 if not specified.
1 Match ‘what’ search term against business categories only.
2 Match ‘what’ search term against business names only.
3 Match ‘what’ search term against a comma separated list of classification IDs.
4 Match ‘what’ term against a category name.
where Any text. Postcode, full or outcode
lat optional Valid latitude If lat is supplied, than long must also be. The latitude to use as a location.
long optional Valid longitude The longitude to use as a location.
radius optional 1...50000 distance in meters, default is 15000 (15k) The radius to use from the location point, must have a valid location to be used.
page optional 0…9 Page of results to view, 0 indexed
items optional 0...50 No of results in a page. Max allowed is 50
types optional 0 Affiliate Deal Comma separated list of voucher types
1 Affiliate Sale
2 Affiliate voucher
3 Sme Deal
4 Sme sale
5 Sme voucher
6 External voucher
7 VAC discount vouchers
8 LiveBookings
9 5pm offers
10 TopTable offers
11 Late room offers
dist optional 0 Local and National Search by promotion distribution. If not specified, defaults to ‘0’ (Local and national).
1 Local only
2 National only
nearestListings optional 1 Based on the given ‘where’ search term, include details of the nearest branch (listing), for any promotion associated to a business chain (group of listings).
listingDetail optional 1 Include the address of each listing described in the XML. This parameter is used to include additional information, such as the address and phone number.
sortOrder optional 0 Best name match Requires ‘what’ to be present. However, if ‘whatType’ set to ‘1’ (i.e. category matching only) then sort option will be defaulted to ‘2’ (popularity). What order to return results in. Default is Popularity (2)
1 Distance,Requires where to be present.
2 Popularity
3 Recent
4 Generic first then Popularity
5 Paid listing first when relevance the same.
type optional Valid type A type from the list of types, ie ‘kettle’ or ‘dishwasher’ The what field can be omitted when providing a type field
mobile optional 0 All vouchers returned
1 Only mobile enabled vouchers returned.

A minimum of either what or where must be specified, otherwise you will receive an INVALID_REQUEST error code back.

The what parameter

The what parameter is in one of several formats depending on the whatType specified as follow:

  • whatType = 0 (default): The what is a normal String which will be used to search for both matching business classifications and business names. what=boots will match both Boots the chemist and shoe shops.
  • whatType = 1: The what is again a normal String but will only be used to match against business classifications, the names of businesses will be ignored, e.g. what=boots will match shoe shops but not Boots the chemists.
  • whatType = 2: The what is again a normal String but will only be used to match against the business names, e.g. what=pizza will match Pizza Hut but not Papa Johns.
  • whatType = 3: This has to be a comma separated list of classification codes (an integer), e.g. what=1,7,97,462. For a list of classifications and their codes please contact BView.
  • whatType = 4: This allows you to specify a single top level category (set of classifications), e.g. what=Eating%20Out. Please contact BView for a list of categories.

Most recent and most popular searches

As an alternative to the parameters defined above you can also request the most popular or most recent vouchers with the following parameter:

  • q=recent: A list of the 20 most recent vouchers added to BView
  • q=popular: A list of the 20 most popular vouchers this week on BView.

These requests do not require any other parameters apart from your key of course (and will ignore anything else sent, pagination will not work).

Output

The response will be an XML document that complies with the schema at http://www.bview.co.uk/xsd/promotion_api.xsd. The promotion API output has the following structure: 

<bview-vouchers>
  <language></language>
  <datum></datum>
  <vouchers>
    <voucher>
      …
    </voucher>
  </vouchers>
</bview-vouchers>

There are 0 to many voucher nodes under the vouchers node. A voucher node may contain the following elements:

Element Description
id Unique reference number for the promotion.
voucherType A String representing the type of promotion. It will be one of: 
 AFFILIATE_DEAL: A particular deal for an affiliate site.
 AFFILIATE_SALE: A general sale for an affiliate site.
 AFFILIATE_VOUCHER: A particular promotion (requiring an affiliate code) for an affiliate site.
 SME_DEAL: A particular deal for an SME business on our site.
 SME_SALE: A sale for an SME business on our site.
 SME_VOUCHER: A particular promotion for an SME business on our site.
 EXTERNAL_VOUCHER: A basic link to a promotion on an external site.
 VAC_DISCOUNT: VAC discount voucher listed on our site.
 LIVE_BOOKING: LiveBookings offer listed on our site.
 FIVEPM_BOOKING: 5pm offer listed on our site.
 TOPTABLE_OFFER: Top table offer listed on our site.
 generic

If false then the promotion is for a specific product or service, otherwise is it’s a generic promotion for the listing.

link A link back to the BView page containing the promotion.
directLink A link direct to the promotion itself. This could be an external site or a BView page containing just the promotion.

LiveBookings and TopTable vouchers link through to the BView online restaurant booking page, compatible for display via an Apple iPhone application, or standard web site page.

affiliateCode A promotional code required to use affiliate vouchers.
title The title of the promotion.
text A description of the promotion.
savingType A brief description of the type of saving, e.g. “33% off”, “2 for 1”, “Special offer” etc.
image An appropriate image to display for the promotion, the node contains two attributes, url and url-thumbnail. URL is for the full size image, url-thumbnail refers to a 90x90 cropped image.
expires The expiry date of the promotion, it contains three attributes, month (January = 1, February = 2 etc), day and year.
listingId The ID of the BView business listing associated to the promotion. This XML element will be excluded for any promotion not associated to a BView listing.
nearestListingId The ID of the BView business listing associated to the promotion. This XML element will be included where the ‘nearestListings’ parameter is set in the request, and the promotion is associated to a chain of BView listings instead of a single BView listing.
address The address of the listing. This element is only included if the request parameter ‘listingDetail’ is set to ‘1’. This element is composed of the following sub-elements:
  • addr1
  • addr2
  • addr3
  • city
  • province
  • postal-code
phone The phone number of the listing, or nearest listing when part of a group. This element is only included if the request parameter ‘listingDetail’ is set to ‘1’.
latitude The latitude of the business in WGS84 format.
longitude The longitude of the business in WGS84 format.
search-proximity The distance in metres, between the business and centre point of the ‘where’ search parameter. If no ‘where’ parameter was supplied in the request, then this element will be excluded.
mlUrn The Market Location ID for this listing. This XML element will be excluded, if no relevant ID exists.
name The name of the business associated to the promotion.
category The business category associated with the voucher (e.g. Butchers, Bakery, Restaurant etc…). This element is composed with the following fields:
  • BView category code.
  • Descriptive name of category.
impression-image the url used to track promotions, it will return a small 1px transparent gif. Calling this URL when displaying the promotion is mandatory to comply with BView T&C's.

Sample of Rececent promotions XML

<?xml version="1.0" encoding="UTF-8"?>
<bview-vouchers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:noNamespaceSchemaLocation="http://www.bview.co.uk/xsd/promotion_api.xsd">
    <language>en</language>
    <datum>WGS84</datum>
    <vouchers>
        <voucher>
            <id>MhjQrSJh3KaD2TXU3oACDstQ</id>
            <voucherType>SME_VOUCHER</voucherType>
            <link>http://www.bview.co.uk/listing/2393672/alexandria-designs-fcl-in-NE26</link>
            <directLink>http://www.bview.co.uk/app/frontend/SmeVoucher?pid=MhjQrSJh3KaD2TXU3oACDstQ</directLink>
            <title>15% off designer fabric and wallcoverings</title>
            <text>15% off all designer fabrics and wallcoverings with this voucher.
                can only be used when purchasing off our website
                not to be used in store
            </text>
            <savingType>Special offer</savingType>
            <listingId>KMMtNErgGsOhov1hbEllcSD-</listingId>
            <mlUrn>CDJW784</mlUrn>
            <name>Alexandria Designs FCL</name>
            <category>
                <category-code>9999</category-code>
                <category-description>Clothing designers</category-description>
            </category>
        </voucher>
        .
        .
        .

Example Authentication error XML

<?xml version="1.0" encoding="UTF-8"?>
<bview-vouchers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:noNamespaceSchemaLocation="http://www.bview.co.uk/xsd/promotion_api.xsd">
    <language>en</language>
    <datum>WGS84</datum>
    <error>
        <error-code>AUTHENTICATION_ERROR</error-code>
    </error>
</bview-vouchers>

Promotion API query examples

Search for pizza, using default whatType(0)

http://www.bview.co.uk/app/frontend/PromotionApi?what=pizza&key=<YOUR KEY> 

<bview-vouchers xsi:noNamespaceSchemaLocation="http://www.bview.co.uk/xsd/promotion_api.xsd">
    <language>en</language>
    <datum>WGS84</datum>
    <vouchers>
        <voucher>
            <id>UZhv4miSSl5O0h6VaZ_vHMEm</id>
            <voucherType>EXTERNAL_VOUCHER</voucherType>
            <generic>true</generic>
            <link>http://www.bview.co.uk/g/ask-restaurants</link>
            <directLink>
                http://www.bview.co.uk/app/frontend/BViewFrame?pid=UZhv4miSSl5O0h6VaZ_vHMEm
                &cid=h5Oyfs_s&t=EXTERNAL_VOUCHER
            </directLink>
            <title>Food to go from £5.95</title>
            <text>Get great Ask food - to go! From £5.95</text>
            <savingType>Special offer</savingType>
            <image url="http://www.bview.co.uk/static/ugc/images/group/lj/ljCWN3eEfKTTNgEqRob595nt.jpg"
                   url-thumbnail="http://www.bview.co.uk/static/ugc/images/group/lj/ljCWN3eEfKTTNgEqRob595nt.jpg"/>
            <name>Ask restaurants</name>
            <category>
                <category-code>1471</category-code>
                <category-description>Pizza Restaurants</category-description>
            </category>
        </voucher>
        .
        .
        .


To get the most recent vouchers

http://www.bview.co.uk/app/frontend/PromotionApi?q=recent&key=<YOUR KEY>

note with the recent query the what or where is not required. 

<bview-vouchers xsi:noNamespaceSchemaLocation="http://www.bview.co.uk/xsd/promotion_api.xsd">
    <language>en</language>
    <datum>WGS84</datum>
    <vouchers>
        <voucher>
            <id>jdBk6fFlkuIINUY82dIiRiCe</id>
            <voucherType>SME_VOUCHER</voucherType>
            <generic>true</generic>
            <link>
                http://www.bview.co.uk/listing/2635577/Fabulous-Masterpieces-in-W14
            </link>
            <directLink>
                http://www.bview.co.uk/app/frontend/SmeVoucher?pid=jdBk6fFlkuIINUY82dIiRiCe&cid=h5Oyfs_s
            </directLink>
            <title>10% Off All Family, Child & Animal Portraits</title>
            <text>
                10% off all portraits when ordered by 14th February 2010. This offer can not be used in conjunction with
                any ther offer by Fabulous Masterpieces.
            </text>
            <savingType>10% off</savingType>
            <image url="http://www.bview.co.uk/static/ugc/images/promotion/8H/8Hio77CtAXj8oJhY6P113fV4.jpg"
                   url-thumbnail="http://www.bview.co.uk/static/ugc/images/promotion/8H/tn_8Hio77CtAXj8oJhY6P113fV4.jpg"/>
            <listingId>3njjaaLLJkg3eMXyScInBElO</listingId>
            <latitude>51.48920939996446</latitude>
            <longitude>-0.2067287684383755</longitude>
            <name>Fabulous Masterpieces</name>
            <category>
                <category-code>82</category-code>
                <category-description>Artists</category-description>
            </category>
        </voucher>
        .
        .
        .

To get the most popular vouchers

http://www.bview.co.uk/app/frontend/PromotionApi?q=popular&key=<YOUR KEY>

note with the recent query the what or where is not required. 

<bview-vouchers xsi:noNamespaceSchemaLocation="http://www.bview.co.uk/xsd/promotion_api.xsd">
    <language>en</language>
    <datum>WGS84</datum>
    <vouchers>
        <voucher>
            <id>UZhv4miSSl5O0h6VaZ_vHMEm</id>
            <voucherType>EXTERNAL_VOUCHER</voucherType>
            <generic>true</generic>
            <link>http://www.bview.co.uk/g/ask-restaurants</link>
            <directLink>
                http://www.bview.co.uk/app/frontend/BViewFrame?pid=UZhv4miSSl5O0h6VaZ_vHMEm
                &cid=h5Oyfs_s&t=EXTERNAL_VOUCHER
            </directLink>
            <title>Food to go from £5.95</title>
            <text>Get great Ask food - to go! From £5.95</text>
            <savingType>Special offer</savingType>
            <image url="http://www.bview.co.uk/static/ugc/images/group/lj/ljCWN3eEfKTTNgEqRob595nt.jpg"
                   url-thumbnail="http://www.bview.co.uk/static/ugc/images/group/lj/ljCWN3eEfKTTNgEqRob595nt.jpg"/>
            <name>Ask restaurants</name>
            <category>
                <category-code>1471</category-code>
                <category-description>Pizza Restaurants</category-description>
            </category>
        </voucher>
        .
        .
        .
Retrieved from "http://api.bview.com/index.php?title=Promotion_API"
Personal tools