API Integration « ServicePros

Welcome to the Nearby Now API Integration Page

If you wish to integrate your website with server-side code, here are some instructions that may help.

CSS and Script Files

jQuery 1.6 or later is required. We recommend using a CDN to serve-up jQuery. For example, to use Google’s jQuery CDN:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

The following css files and script files will need to be loaded for pages utilizing the Nearby Now API content:
Note, these must come after jQuery has been loaded

<link href="https://d2gwjd5chbpgug.cloudfront.net/v3/css/nnplugin.min.css" rel="stylesheet" type="text/css" />
<script src="https://d2gwjd5chbpgug.cloudfront.net/v3/scripts/heatmap.min.js"></script>

API Endpoints

The Nearby Now API supports multiple content modes, each with the following endpoints:

Recent Reviews	https://api.sidebox.com/plugin/nearbyreviews
Service Area Map & Recent Check-ins	https://api.sidebox.com/plugin/nearbyservicearea
Service Area Review Combo	https://api.sidebox.com/plugin/nearbyserviceareareviewcombo
Regional & Nation-wide Combination	https://api.sidebox.com/plugin/nationwideserviceareareviewcombo
Google Reviews	https://api.sidebox.com/plugin/googlereviews
Audio Testimonials	https://api.sidebox.com/plugin/testimonials
Photo & Video Gallery	https://api.sidebox.com/plugin/photogallery
Website FAQ	https://api.sidebox.com/plugin/faq

Parameters

Most API endpoints support a common set of parameters, with the following exceptions: the combination endpoint uses “reviewcount”, “reviewstart”, “checkincount”, and “checkinstart”, where the other two urls simply use “count” and “start”. It also includes a few additional parameters as described below. Nation-wide, and media endpoints also have unique params. The storefronttoken parameter is a unique identifier (required) that you can find under the API tab in the settings page of the admin site.

/nearbyserviceareareviewcombo

state="FL" – Optional & case insensitive. Must be used in conjunction with “city”. Indicates the city and state for which the review and check-in content will be rendered in the markup, and where the map will be centered. If no city and state are specified, review and check-in content will be rendered without respect to its local city/state, and the map center will be calculated based on an approximate center of all reviews.
city="Orlando" – Optional & case insensitive. Must be used in conjunction with “state” (See above). Can be a comma separated list of city names
showmap="yes" – Optional, defaults to “yes”. If specified as anything other than “yes”, then the map will not be displayed, and only the rendered review and check-in content will be shown.
reviewstart="1" – Optional, defaults to “1”. Indicates the starting review number to render, based on a reverse chronological order, and may be used for paging.
reviewcount="15" – Optional, defaults to 15. Specifies the number of reviews to render based on a reverse chronological order.
checkinstart="1" – Optional, defaults to “1”. Indicates the starting check-in number to render, based on a reverse chronological order, and may be used for paging.
checkincount="15" – Optional, defaults to 15. Specifies the number of check-ins to render based on a reverse chronological order.
zoomlevel="11" – Optional. Indicates the initial zoom level of the map, and may be a number between 8 and 14, where 8 is a larger area with less detail, and 14 is a small area with more detail. If not specified, Nearby Now will calculate an appropriate zoom level.
reviewcityurl="http://www.mydomain.com/service-area-{city}-{state}" – Optional. If specified, a set of url’s will be rendered under the title “Our Reviews by City”. Each city that has at least one local review will be rendered as a link that fits the specified pattern, where “{city}” will be replaced by the lowercase name of the city, and “{state}” will be replaced by the lowercase two character abbreviation for the state. If a city name has more than one word, hyphens will replace the spaces. In the example above, the url rendered for Fort Worth, Texas will be “http://www.mydomain.com/service-area-fort-worth-tx”.
mapsize="large" – Optional, defaults to “large”. May be “small” to render a small map, “medium” for a bigger map, and “large” for a large map. The containing element of the shortcode dictates the width of the map – this parameter adjusts the height.
mapscrollwheel="no" – Optional, defaults to “no”. If specified as “yes”, then the mouse scroll wheel may be used to change the zoom level of the interactive map.
fblike="no" – Optional, defaults to “no”. If specified as “yes”, a Facebook like button plugin will be rendered below each rendered review.
fbcomment="no" – Optional, defaults to “no”. If specified as “yes”, a Facebook comment plugin will be rendered below each rendered review.
techemail="tech@yourdomain.com" – Optional. If specified, the rendered reviews and check-ins will be limited to those of the technician specified. This is often used for technician specific pages, where each technician has his or her own page of reviews and check-in content. Consider using in conjunction with showmap=”no”, and without a city or state parameter.
serviceareaname – Optional, defaults to the name of the city(s) from the city param. If combining multiple cities you might say something like “East Valley”.
referrer – Address of the webpage that linked to the resource being requested.
hosturl – The full address of current request.
showphotos="yes" – Optional, defaults to “yes”. If specified as “no”, plugin output will not include checkin photos.
showminimap="yes" – Optional, defaults to “yes”. If specified as “no”, plugin output will not include a Google Maps image next to a review.
tags="sales-team, installers" – Optional. If specified, plugin output will be restricted to content created from users with the assigned tags provided.
includegooglereviews="yes" – Optional. If specified, plugin output includes Google reviews that have been assigned.

/nearbyservicearea

state="FL" – Optional & case insensitive. Must be used in conjunction with “city”. Indicates the city and state for which the check-ins will be rendered in the markup, and where the map will be centered. If no city and state are specified, check-ins will be rendered without respect to the check-in local city/state, and the map center will be calculated based on an approximate center of all check-ins.
city="Orlando" – Optional & case insensitive. Must be used in conjunction with “state” (See above). Can be a comma separated list of city names
showmap="yes" – Optional, defaults to “yes”. If specified as anything other than “yes”, then the map will not be displayed, and only the rendered check-ins will be shown.
start="1" – Optional, defaults to “1”. Indicates the starting check-in number to render, based on a reverse chronological order, and may be used for paging.
count="15" – Optional, defaults to 15. Specifies the number of check-ins to render based on a reverse chronological order.
zoomlevel="11" – Optional. Indicates the initial zoom level of the map, and may be a number between 8 and 14, where 8 is a larger area with less detail, and 14 is a small area with more detail. If not specified, Nearby Now will calculate an appropriate zoom level.
mapscrollwheel="no" – Optional, defaults to “no”. If specified as “yes”, then the mouse scroll wheel may be used to change the zoom level of the interactive map.
fblike="no" – Optional, defaults to “no”. If specified as “yes”, a Facebook like button plugin will be rendered below each rendered check-in.
fbcomment="no" – Optional, defaults to “no”. If specified as “yes”, a Facebook comment plugin will be rendered below each rendered check-in.
techemail="tech@yourdomain.com" – Optional. If specified, the rendered check-ins will be limited to those of the technician specified. This is often used for technician specific pages, where each technician has his or her own page of check-in content. Consider using in conjunction with showmap=”no”, and without a city or state parameter.
referrer – Address of the webpage that linked to the resource being requested.
hosturl – The full address of current request.
showphotos="yes" – Optional, defaults to “yes”. If specified as “no”, plugin output will not include checkin photos.
tags="sales-team, installers" – Optional. If specified, plugin output will be restricted to content created from users with the assigned tags provided.

/nearbyreviews

state="FL" – Optional & case insensitive. Must be used in conjunction with “city”. Indicates the city and state for which the reviews will be rendered in the markup, and where the map will be centered. If no city and state are specified, reviews will be rendered without respect to the author’s local city/state, and the map center will be calculated based on an approximate center of all reviews.
city="Orlando" – Optional & case insensitive. Must be used in conjunction with “state” (See above). Can be a comma separated list of city names
showmap="yes" – Optional, defaults to “yes”. If specified as anything other than “yes”, then the map will not be displayed, and only the rendered reviews will be shown.
start="1" – Optional, defaults to “1”. Indicates the starting review number to render, based on a reverse chronological order, and may be used for paging.
count="15" – Optional, defaults to 15. Specifies the number of reviews to render based on a reverse chronological order.
zoomlevel="11" – Optional. Indicates the initial zoom level of the map, and may be a number between 8 and 14, where 8 is a larger area with less detail, and 14 is a small area with more detail. If not specified, Nearby Now will calculate an appropriate zoom level.
mapscrollwheel="no" – Optional, defaults to “no”. If specified as “yes”, then the mouse scroll wheel may be used to change the zoom level of the interactive map.
fblike="no" – Optional, defaults to “no”. If specified as “yes”, a Facebook like button plugin will be rendered below each rendered review.
fbcomment="no" – Optional, defaults to “no”. If specified as “yes”, a Facebook comment plugin will be rendered below each rendered review.
techemail="tech@yourdomain.com" – Optional. If specified, the rendered reviews will be limited to those of the technician specified. This is often used for technician specific pages, where each technician has his or her own page of review content. Consider using in conjunction with showmap=”no”, and without a city or state parameter.
referrer – Address of the webpage that linked to the resource being requested.
hosturl – The full address of current request.
showminimap="yes" – Optional, defaults to “yes”. If specified as “no”, plugin output will not include a Google Maps image next to a review.
tags="sales-team, installers" – Optional. If specified, plugin output will be restricted to content created from users with the assigned tags provided.
includegooglereviews="yes" – Optional. If specified, plugin output includes Google reviews that have been assigned.

/nationwideserviceareareviewcombo

Note: This is a feature for the U.S. only. We plan to support additional countries in the future.

state="FL" – Optional for Nation-Wide, required for Regional – & case insensitive. Indicates the state for which the reviews will be rendered in the markup, and where the map will be centered.
lat="33.4159981" – Required. The latitude where you’d like the map to center.
long="-98.5794797" – Required. The longitude where you’d like the map to center.
mapsize="regional" – Optional, defaults to “regional”. Use regional to display a regional map, nationwide to display a nation-wide map.
reviewpinmax="100" – Optional. The maximum number of review pins to display (either as pins or clusters).
cluster="yes" – Optional, defaults to “yes”. Specifies is groups of review pins close together should display as a cluster (We recommend you cluster to prevent close pins from overlapping)
tags="sales-team, installers" – Optional. If specified, plugin output will be restricted to content created from users with the assigned tags provided.

/googlereviews

state="FL" – Optional & case insensitive. Must be used in conjunction with “city”. Indicates the city and state for which the reviews will be rendered in the markup, and where the map will be centered. If no city and state are specified, reviews will be rendered without respect to the author’s local city/state, and the map center will be calculated based on an approximate center of all reviews.
city="Orlando" – Optional & case insensitive. Must be used in conjunction with “state” (See above). Can be a comma separated list of city names
showmap="yes" – Optional, defaults to “yes”. If specified as anything other than “yes”, then the map will not be displayed, and only the rendered reviews will be shown.
start="1" – Optional, defaults to “1”. Indicates the starting review number to render, based on a reverse chronological order, and may be used for paging.
count="15" – Optional, defaults to 15. Specifies the number of reviews to render based on a reverse chronological order.
zoomlevel="9" – Optional. Indicates the initial zoom level of the map, and may be a number between 8 and 14, where 8 is a larger area with less detail, and 14 is a small area with more detail. If not specified, Nearby Now will calculate an appropriate zoom level.
mapscrollwheel="no" – Optional, defaults to “no”. If specified as “yes”, then the mouse scroll wheel may be used to change the zoom level of the interactive map.
techemail="tech@yourdomain.com" – Optional. If specified, the rendered reviews will be limited to those of the technician assigned to the Google Review. This is often used for technician specific pages, where each technician has his or her own page of review content. Consider using in conjunction with showmap=”no”, and without a city or state parameter.
referrer – Address of the webpage that linked to the resource being requested.
hosturl – The full address of current request.
showminimap="yes" – Optional, defaults to “yes”. If specified as “no”, plugin output will not include a Google Maps image next to a review.
googlelocation_id="12345" – Optional. If specified, plugin output will be to the specific Google Location provided.

/testimonials

playlist="play_list_name" – Required & case insensitive. The name of the play list that you want to display on the page.
showTranscription="true" – Optional. If you’ve had audio testimonials transcribed, set this option to true to have the text display along with the audio.
start="1" – Optional, defaults to “1”. Indicates the starting audio testimonial number to render, based on a reverse chronological order, and may be used for paging.
count="15" – Optional, defaults to 15. Specifies the number of audio testimonial to render based on a reverse chronological order.

/photogallery

start="1" – Optional, defaults to “1”. Indicates the starting photo/video number to render, based on a reverse chronological order, and may be used for paging.
count="10" – Optional, defaults to 10. Specifies the number of photos/videos to render based on a reverse chronological order.
tags="sales-team, installers" – Optional. If specified, plugin output will be restricted to content created from users with the assigned tags provided.

/faq

topic="some-topic-name" – Required. Name (Code) of the optic FAQs you wish to display.
count="10" – Optional, defaults to 10. Specifies the number of faqs to render.

Example PHP Code

Place the following code wherever you need to render the API content:

Note, make sure that allow_url_fopen is enabled in your PHP server settings so that external API calls can be made to our servers.

<?php //Base endpoint for all API calls $endpoint = "https://api.sidebox.com/plugin"; //The resouce is the API Endpoint you'll be making a web request to $resource = "/nearbyreviews"; //$resource = "/nearbyservicearea"; //$resource = "/nearbyserviceareareviewcombo"; //$resource = "/nationwideserviceareareviewcombo"; //$resource = "/testimonials"; //$resource = "/photogallery"; //required API param $token = "get the Storefront API Token from the Nearby Now admin site"; //optional API params $agent = urlencode($_SERVER['HTTP_USER_AGENT']); $state = ""; // The abbreviated state. For example, Arizona should be "AZ" $city = urlencode(""); $showMap = ""; $showFavorites = ""; $start = ""; $count = ""; $zoom = ""; $reviewCityUrl = ""; $mapSize = ""; $mapScrollWheel = ""; $fbLike = ""; $fbComment = ""; //Optinal params for the Nearby Service Area Seview Combo resource $techEmail = urlencode(""); $reviewStart = ""; $checkinStart = ""; $reviewCount = ""; $checkinCount = ""; //Optinal params for the Regional & Nation-wide Combination (beta) $lat = ""; $long = ""; $reviewpinmax = ""; $cluster = ""; //Required params for the audio testimonials $playlist = urlencode(""); //Optinal params for the Nearby Service Area Seview Combo resource $showTranscription = ""; $referrer = $_SERVER['HTTP_REFERER']; $hostUrl = "http" . (($_SERVER['SERVER_PORT'] == 443) ? "s://" : "://") . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']; ?><?php // /nearbyreviews example params $query = "?storefronttoken=$token&state=$state&city=$city&zoomlevel=$zoom&start=$start&count=$count&showmap=$showMap&mapsize=$mapSize&mapscrollwheel=$mapScrollWheel&fblike=$fbLike&fbcomment=$fbComment&showfavorites=$showFavorites&agent=$agent&referrer=$referrer&hosturl=$hostUrl"; // /nearbyservicearea example params //$query = "?storefronttoken=$token&state=$state&city=$city&zoomlevel=$zoom&start=$start&count=$count&showmap=$showMap&mapsize=$mapSize&mapscrollwheel=$mapScrollWheel&fblike=$fbLike&fbcomment=$fbComment&showfavorites=$showFavorites&agent=$agent"; // /nearbyserviceareareviewcombo example params //$query = "?storefronttoken=$token&state=$state&city=$city&zoomlevel=$zoom&reviewcityurl=$reviewCityUrl&reviewstart=$reviewStart&checkinstart=$checkinStart&reviewcount=$reviewCount&checkincount=$checkinCount&showmap=$showMap&mapsize=$mapSize&mapscrollwheel=$mapScrollWheel&fblike=$fbLike&fbcomment=$fbComment&showfavorites=$showFavorites&agent=$agent"; // /nationwideserviceareareviewcombo example params //$query = "?storefronttoken=$token&state=$state&zoomlevel=$zoom&mapsize=$mapSize&lat=$lat&long=$long&reviewpinmax=$reviewpinmax&cluster=$cluster&agent=$agent"; // /photogallery example params //$query = "?storefronttoken=$token&start=$start&count=$count&agent=$agent"; // /testimonials example params //$query = "?storefronttoken=$token&start=$start&count=$count&playlist=$playlist&showTranscription=$showTranscription&agent=$agent"; $url = "$endpoint$resource$query"; $response = file_get_contents($url); echo $response; ?>

Example C# ASP.NET MVC Code

Use the following code in your controller to retrieve the API content:
Looking for an ASP.NET Web Forms example? https://github.com/NearbyNow/NearbyNow-aspnetwebformexample

public class ApiSampleController : Controller { private const string api = "https://api.sidebox.com/plugin/nearbyreviews?storefronttoken={0}&state={1}&city={2}&zoomlevel={3}&radius={4}&showmap={5}&techemail={6}&mapscrollwheel={7}&fblike={8}&fbcomment={9}&agent={10}&count={11}"; private const string StorefrontToken = "get this from the Nearby Now admin site"; public ActionResult NearbyNowReviews(String State, String City) { var agent = Request.UserAgent; var wc = new WebClient(); ViewBag.NearbyNowContent = wc.DownloadString(String.Format(api, HttpUtility.UrlEncode(StorefrontToken), HttpUtility.UrlEncode(State), HttpUtility.UrlEncode(City), "", // zoomlevel "", // radius "", // showmap "", // techemail "", // mapscrollwheel "", // fblike "", // fbcomment HttpUtility.UrlEncode(agent), "") ); // count return View(); } }public class ApiSampleController : Controller { private const string api = "https://api.sidebox.com/plugin/nearbyserviceareareviewcombo?storefronttoken={0}&state={1}&city={2}&zoomlevel={3}&radius={4}&showmap={5}&techemail={6}&mapscrollwheel={7}&fblike={8}&fbcomment={9}&agent={10}"; private const string StorefrontToken = "get this from the Nearby Now admin site"; public ActionResult NearbyNowReviews(String State, String City) { var agent = Request.UserAgent; var wc = new WebClient(); ViewBag.NearbyNowContent = wc.DownloadString(String.Format(api, HttpUtility.UrlEncode(StorefrontToken), HttpUtility.UrlEncode(State), HttpUtility.UrlEncode(City), "", // zoomlevel "", // radius "", // showmap "", // techemail "", // mapscrollwheel "", // fblike "", // fbcomment HttpUtility.UrlEncode(agent)) ); // count return View(); } }public class ApiSampleController : Controller { private const string api = "https://api.sidebox.com/plugin/nearbyservicearea?storefronttoken={0}&state={1}&city={2}&zoomlevel={3}&radius={4}&showmap={5}&techemail={6}&mapscrollwheel={7}&fblike={8}&fbcomment={9}&agent={10}&count={11}"; private const string StorefrontToken = "get this from the Nearby Now admin site"; public ActionResult NearbyNowReviews(String State, String City) { var agent = Request.UserAgent; var wc = new WebClient(); ViewBag.NearbyNowContent = wc.DownloadString(String.Format(api, HttpUtility.UrlEncode(StorefrontToken), HttpUtility.UrlEncode(State), HttpUtility.UrlEncode(City), "", // zoomlevel "", // radius "", // showmap "", // techemail "", // mapscrollwheel "", // fblike "", // fbcomment HttpUtility.UrlEncode(agent), "") ); // count return View(); } }<--Finally, render the content in your view using the following code:!--> @Html.Raw(ViewBag.NearbyNowContent)

Example Ruby Code for Rails/Sinatra

Use the following code in your controller/model/helper-class to retrieve the API content:

require 'rest-client' #resource = 'https://api.sidebox.com/plugin/nearbyreviews' resource = 'https://api.sidebox.com/plugin/servicearea' html = RestClient.get resource, { :params => { 'storefronttoken' => '{client_api_token}', 'state' => 'AZ', 'city' => 'Phoenix', 'count' => 20 } } puts htmlrequire 'rest-client' resource = 'https://api.sidebox.com/plugin/nearbyserviceareareviewcombo' html = RestClient.get resource, { :params => { 'storefronttoken' => '{client_api_token}', 'state' => 'AZ', 'city' => 'Phoenix', 'checkincount' => 20, 'reviewcount' => 20 } } puts html

Javascript Reviews Widget

Looking for our embed-able Javascript Reviews Widget? You can find that here.

Photo & Video Gallery Widget

Looking for our embed-able Javascript Photo & Video Gallery Widget? You can find that here.

Random Recent Reviews

Looking to build a Javascript slider and need a JSON endpoint to fill it with random review data? You can find that here.

Responsive Design for custom implementations

The following is an example of making the Nearby Now plugin content mobile friendly. Keep in mind that this is a generic example and you should use CSS that adheres to your own site responsive guidelines:

@media only screen and (max-device-width : 480px) { .nn-review-outer-cont { font-size:180% !important; /* Your mileage may vary depending on your website font */ } .nn-combo-left { width:100% !important; } .nn-combo-right { width:100% !important; } p.nn-review-body, p.nn-samap-body { padding-left: 0.5em !important; margin-left: 0px !important; background-image: none !important; } div.nn-review-footer { margin-left: 3px !important; margin-right: 3px !important; padding: 1em !important; } }

Google Maps API

Your website may be required to obtain a Google Maps API Key in order to render maps on your web pages. The Google Maps API Key should be saved to your storefront. Here’s how to obtain a Google Maps API Key:

Login to https://console.developers.google.com/apis/ – you will need to create a free Google account if you do not already have one.
Navigate to the API Manager: https://console.developers.google.com/apis/library
From The Google APIs tab, setup the following Google APIs: Google Maps JavaScript API and Google Static Maps API. Click into each one and then click the blue “Enabled” button.
Once you have enabled the two APIs, click on “credentials:”
Click on the blue “Create Credentials” button. Give the credentials a name you will remember, such as the company name, or Company and Nearby Now Maps.
Record the generated Key. This is what you’ll save in your Storefront.

To save the Google Maps API Key to your storefront go to Settings > Company Profile > Google Maps API Key.

Write API

We have multiple endpoints that enable you to create checkins and generate review requests from your own systems.

Checkin API

The Checkin API allows agencies and clients to generate new checkins from their own systems. Learn More

Review Request API

We also have a Review Request API that allows agencies and clients to generate new survey requests on behalf of their customers. Learn More

API Integration