Shop Local
Introduction
Shop Local lets you place a button or link onto your site that lets visitors discover independent bookstores nearby that have stock of your product. A simple HTTP request is easily embedded in your web page or blog by including a JavaScript file and adding html tags wherever you want the button(s) to be located.
Usually, each HTML tag will include the product’s EAN, UPC or ISBN. This will prioritize the stores within a radius that have the item in stock (or on order) followed by other independent stores registered with Bookmanager. If a product code is not passed, it will simply list all stores within the radius. Results are retrieved from our server only when the visitor clicks the button/link. Clicking on a store will direct them to their website, usually with the title displayed and ready for purchase.
If you already have the latitude/longitude of the visitor, simply include that with the request. You can also include a parameter that instructs our widget to request this when they click the button. If neither option is used or the visitor does not allow disclosing their location, they will still have the option to provide a postal code. The visitor’s location is required to prioritize the stores nearby.
For optimal consumer experience, we suggest that you pass an EAN/UPC/ISBN at every opportunity. If you already have their lat/long, then passing that makes the experience fast and seamless. If you allow our API to request their location, then the experience is almost as good. Without a lat/long visitors will need to enter a postal code to get any results. The default radius of 100km may seem too wide for large cities, however, consider that visitors in small or rural communities might not see any stores if you default to a small radius.
Authentication
To use Shop Local, you will need an API key. Obtaining a key is free but requires that you have an account with Bookmanager. You then add the url of each site the widget will be used, otherwise the visitor will see an “unauthorized” error when they try to use it.
There is no charge for this service, however, we do throttle requests to prevent abuse and overloading the system.
Basic usage
HTML:
Add the <div> tag where you would like the button or link to appear, then add the <script> tag just before the closing body tag:
<html>
<head></head>
<body>
<section>
<!-- Add div where you would like to see the button or link -->
<div class="tbm_shop_local" data-options="
{
'api_key' : 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
}"
/>
</section>
<!-- Add the script just before the closing body tag -->
<script src="https://bookmanager.com/public/api/tbm-shop-local.js" ></script>
</body>
</html>
EXAMPLE:
Set Location
You can pass location data (latitude and longitude) to display the results as a dropdown without the visitor having to input their postal code.
HTML:
<html>
<head></head>
<body>
<section>
<!-- Add lat, long and product code -->
<div class="tbm_shop_local" data-options="
{
'api_key' : 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'product_code' : '9781571313560',
'latitude' : '49.8879519',
'longitude' : '-119.4960106'
}"
/>
</section>
<!-- Add the script just before the closing body tag -->
<script src="https://bookmanager.com/public/api/tbm-shop-local.js" ></script>
</body>
</html>
EXAMPLE:
Request Location
Alternatively, you can have the browser request location data from the user and display the results approved.
HTML:
<html>
<head></head>
<body>
<section>
<!-- Add request_location flag -->
<div class="tbm_shop_local" data-options="
{
'api_key' : 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'product_code' : '9781571313560',
'request_location' : 'true'
}"
/>
</section>
<!-- Add the script just before the closing body tag -->
<script src="https://bookmanager.com/public/api/tbm-shop-local.js" ></script>
</body>
</html>
EXAMPLE:
Dropdown
If you provide a location, or a visitor has location services enabled, the local stores can be displayed in a dropdown for convenience. Please preview first, as this may not be suitable for some websites.
HTML:
<html>
<head></head>
<body>
<section>
<!-- Add request_location flag -->
<div class="tbm_shop_local" data-options="
{
'api_key' : 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'product_code' : '9781571313560',
'request_location' : 'true'
'enable_dropdown' : 'true'
}"
/>
</section>
<!-- Add the script just before the closing body tag -->
<script src="https://bookmanager.com/public/api/tbm-shop-local.js" ></script>
</body>
</html>
EXAMPLE:
Customize Image
You can change the button label to use an image instead by passing the "image" field for the dropdown or search pop-up.
HTML:
<html>
<head></head>
<body>
<section>
<!-- Add label to the options to change the label -->
<div class="tbm_shop_local" data-options="
{
'api_key' : 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'image' : 'https://bookmanager.com/public/api/btns/Shop Local Button.png'
}"
/>
</section>
<!-- Add the script just before the closing body tag -->
<script src="https://bookmanager.com/public/api/tbm-shop-local.js" ></script>
</body>
</html>
EXAMPLE:
Options
Options are added via the data-options attribute in JSON format. Below is a list of available options:
| Option | Description | Default | |
|---|---|---|---|
| api_key | 32 character alphanumeric key | Required | - |
| product_code | ISBN, UPC or EAN code | Optional | - |
| latitude | Latitude | Optional | - |
| longitude | Longitude | Optional | - |
| distance_km | Radius in kilometers | Optional | 100 |
| label | Label for dropdown | Optional | Shop Local |
| request_location | Request location from the browser | Optional | false |
| image | Replace button with an image | Optional | - |
| enable_dropdown | Set to true to enable dropdown | Optional | false |
Generate Sample Code
Use this tool to configure options and generate the HTML.