Knowledge Base: Profile Feed API Documentation

Last Updated Sep. 28, 2012

This article is intended for a technical audience. As a courtesy we provide some technical assistance via email support, but such requests are best-effort and as technical staff are available.

Our profile feed API provides basic profile information and recent reviews in a JSON format to allow custom integration with your website or other services.

To access your feed, send a GET request over HTTP or HTTPS to the resource below:

http://ratelobby.com/api/feed/1.0/


Parameters:

id(Required.) Your business ID, see https://ratelobby.com/manage/integration?tab=api
include_custom_questionsSet to 1 to include custom questions (if any) with overall stats and individual answers. (By default this data is not returned.)
featured_firstSet to 0 to return reviews in strictly chronological order. (By default featured reviews come first, the same order as on our profile pages.)
limitMaximum number of reviews to return from 0 - 30 inclusive, though this is also restricted by how many reviews your plan includes. (A limit of 0 may be useful if you only want your overall details.)


Response:

The sample response body below shows the JSON structure and all the possible elements. Note that some elements will not always be returned. In the context of custom questions the "type" element may be set to either "text" (open response) or "rating" (out of 5).

Query: http://ratelobby.com/api/feed/1.0/?id=1&include_custom_questions=1

{
	"business_name": "My Company",
	"rating_average": 5.0,
	"rating_count": 3,
	"profile_uri": "http://ratelobby.com/review/1/my-company",
	"submit_uri": "http://ratelobby.com/submit/?id=1",
	"ratelobby_logo": {
		"s": "//ratelobby.com/api/img/logo-145x40.png",
		"m": "//ratelobby.com/api/img/logo-200x55.png",
		"l": "//ratelobby.com/api/img/logo-290x80.png",
		"xl": "//ratelobby.com/api/img/logo-400x110.png"
	},
	"custom_questions": [
		{
			"type": "rating",
			"question": "How would you rate our monthly featured selections?",
			"response_count": 1,
			"response_average": 5.0
		},
		{
			"type": "text",
			"question": "Location:",
			"response_count": 1
		}
	],
	"reviews": [
		{
			"name": "John Doe",
			"rating": 5,
			"comment": "This company absolutely sets an example for the industry! Had them demonstrate a profile for my instruction manual-themed office party last year and everybody thought they were so illustrative. Wouldn't trust any other sample company for my demonstrative or explanatory purposes.",
			"timestamp": 1332451170,
			"uri": "http://ratelobby.com/review/1/my-company?comment=101",
			"business_reply": {
				"comment": "Thanks, John. We try! :)",
				"timestamp": 1332511658
			}
		},
		{
			"name": "Cindy L.",
			"rating": 5,
			"comment": "We recently asked this company to be an example in our screencast, and wow did they deliver! Not only did they fill the space, but they even took the time to make cheesy jokes about being a sample company.",
			"timestamp": 1332615325,
			"uri": "http://ratelobby.com/review/1/my-company?comment=102",
			"custom_questions": [
				{
					"type": "rating",
					"question": "How would you rate our monthly featured selections?",
					"response": 5
				},
				{
					"type": "text",
					"question": "Location:",
					"response": "New York, NY"
				}
			]
		}
	]
}

IMPORTANT: To avoid cross-site scripting (XSS) and other rendering problems you need to properly handle HTML entities.

For example, if a reviewer writes <script>alert("hello")</script> in his or her review, we will return exactly that. You need to convert it to &lt;script&gt;alert(&quot;hello&quot;)&lt;/script&gt; to render properly and prevent browsers from executing that code on your HTML page! To be safe, you should do this for all strings you are outputting, including names, custom questions, etc.


Examples:

PHP: Use htmlentities(). In addition, you may want to use nl2br() to convert line breaks to <br /> (be sure to do this after htmlentities() so you don't encode the break tags!).

ASP.NET: Use HttpUtility.HtmlEncode(). You may want to use Replace("\n", "<br />") to convert line breaks (after HtmlEncode() so you don't encode the break tags!).

JavaScript: Use the innerText property as opposed to innerHTML.



Sample Code

The PHP example below shows how you might use the profile feed to generate a customer reviews page on your own site.

<?php

// TODO You'll need to update this with your appropriate ID
$feed_uri = 'http://ratelobby.com/api/feed/1.0/?id=1&limit=10';


// Initialize cURL handle
$curl = curl_init($feed_uri);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

// Fetch the feed and parse the JSON
$ratelobby = json_decode(curl_exec($curl));

curl_close($curl);


// PHP's json_decode() returns NULL if it fails to parse the input
if($ratelobby === null) {
	echo 'Error: Check cURL settings.';
}
// RateLobby feed API returns a response body of the form {"error":"message"} if something goes wrong
elseif(isset($ratelobby->error)) {
	echo 'Error: ', $ratelobby->error;
}
else {
	echo '<h1>What our customers say...</h1>';
	
	echo "<p>Rated {$ratelobby->rating_average} out of 5 based on {$ratelobby->rating_count} reviews.</p>";

	// Output reviews
	foreach($ratelobby->reviews as $review) {
		echo '<div class="review">',
			'<p>', nl2br(htmlentities($review->comment)), '</p>',
			'<p>', $review->rating, ' star rating by <strong>', htmlentities($review->name), '</strong></p>',
		'</div>';
	}

	echo '<p>',
		'Powered by <img src="', $ratelobby->ratelobby_logo->s, '" alt="RateLobby" style="vertical-align:middle;" /> ',
		'<a href="', $ratelobby->profile_uri, '">See more reviews</a> or <a href="', $ratelobby->submit_uri, '">add yours</a>.',
	'</p>';
}

?>

Filed Under: Site Integration

Browse categories

Can't find the answer you're looking for? Contact Us

© RateLobby, LLC | Privacy | Terms of Service | Help | Contact