Introduction
The GoodPickle.com API allows web developers to access various data about their user account for use in developing web applications. All information is available in JSON, XML, and JSONP formats.
Setup
In order to begin making requests to the API, you need to register your website domain and receive an API key. The generated key is required to make requests to the API.
Endpoint URL
All requests to the API begin with the following endpoint:
http://api.goodpickle.com/The name of the method you wish call along with its parameters follow the trailing '/'
Results
The root object returned by every API call is named 'results'. It includes an object called 'status'. If the value of status is "OK", your API call was successful. Otherwise 'status' will contain an error message.
Methods
getTestimonialsReceived
Description: Retrieve various information about the latest approved, received testimonials such as the title, body, location, member's and reviewer's profile picture, etc.
Parameters:
Name
Description
Default Value
Required
api_key
Your developer API key
(NONE)
Required
format
The format of the returned data. Valid values are "json" and "xml"
json
Optional
callback
The name of your javascript callback function. If you include this parameter, the results will be returned as JSONP, calling your function with a results object as the first parameter. Note: this will not do anything if you specify the 'format' parameter as xml.
(NONE)
Optional
type
The type of testimonials you wish to retrieve. Valid values are "all", "video", "audio", "scan", and "signature"
all
Optional
page
The page number of testimonials you wish to retrieve. Testimnonials are ordered by their approved date, newest first.
1
Optional
items
The number of testimonials to retrieve per page. The maximum value is 10
10
Optional
Example request:
http://api.goodpickle.com/getTestimonialsReceived?api_key=YOUR_API_KEY&format=xml&type=scan&items=5
Example response:
{
"results": {
"status": "OK",
"page": 1,
"items_per_page": 5,
"type": "all",
"num_results": 2,
"testimonials": [
{
"title": "Awesome Job!!",
"body": "Company XYZ really knows their stuff! They did a great job!\r\n\r\nJohn Smith - Somewhere, AZ",
"how_old": "2 days ago",
"total_comments": 4,
"date": "2011-09-27 15:24:31",
"review_url": "http://www.goodpickle.com/site/review/awesome-job-111",
"location": null,
"media_type": "scan",
"media_src": "http://www.goodpickle.com/media/scans/98_327/scan111.jpg",
"reviewer_url": "http://www.goodpickle.com/memberProfile/03",
"reviewer_name": "John Smith",
"reviewer_pic": "http://www.goodpickle.com/media/profilePic/03/profileSmall.jpg",
"member_url": "http://www.goodpickle.com/XYZ",
"member_name": "Company XYZ",
"member_pic": "http://www.goodpickle.com/media/profilePic/04/profileSmall.jpg"
},
{
"title": "Great deals and prices",
"body": "I found exactly what I was looking for, Thanks!",
"how_old": "1 month ago",
"total_comments": 1,
"date": "2011-08-27 15:22:32",
"review_url": "http://www.goodpickle.com/site/review/great-deals-and-prices-100",
"location": "Location X",
"media_type": "signature",
"media_src": "http://www.goodpickle.com/media/signatures/98_100/signature100.jpg",
"reviewer_url": "http://www.goodpickle.com/memberProfile/33",
"reviewer_name": "Jane Doe",
"reviewer_pic": "http://www.goodpickle.com/media/profilePic/33/profileSmall.jpg",
"member_url": "http://www.goodpickle.com/XYZ",
"member_name": "Company XYZ",
"member_pic": "http://www.goodpickle.com/media/profilePic/04/profileSmall.jpg"
}
]
}
}
getTestimonialsWritten
Description: Retrieve various information about the latest approved, written testimonials such as the title, body, location, member's and reviewer's profile picture, etc.
Parameters:
Name
Description
Default Value
Required
api_key
Your developer API key
(NONE)
Required
format
The format of the returned data. Valid values are "json" and "xml"
json
Optional
callback
The name of your javascript callback function. If you include this parameter, the results will be returned as JSONP, calling your function with a results object as the first parameter. Note: this will not do anything if you specify the 'format' parameter as xml.
(NONE)
Optional
page
The page number of testimonials you wish to retrieve. Testimnonials are ordered by their approved date, newest first.
1
Optional
items
The number of testimonials to retrieve per page. The maximum value is 10
10
Optional
Example request:
http://api.goodpickle.com/getTestimonialsWritten?api_key=YOUR_API_KEY&format=json&items=5
Example response:
{
"results": {
"status": "OK",
"page": 1,
"items_per_page": 5,
"type": "all",
"num_results": 2,
"testimonials": [
{
"title": "Awesome Job!!",
"body": "Company XYZ really knows their stuff! They did a great job!\r\n\r\nJohn Smith - Somewhere, AZ",
"how_old": "2 days ago",
"total_comments": 4,
"date": "2011-09-27 15:24:31",
"review_url": "http://www.goodpickle.com/site/review/awesome-job-111",
"location": null,
"media_type": "scan",
"media_src": "http://www.goodpickle.com/media/scans/98_327/scan111.jpg",
"reviewer_url": "http://www.goodpickle.com/memberProfile/03",
"reviewer_name": "John Smith",
"reviewer_pic": "http://www.goodpickle.com/media/profilePic/03/profileSmall.jpg",
"member_url": "http://www.goodpickle.com/XYZ",
"member_name": "Company XYZ",
"member_pic": "http://www.goodpickle.com/media/profilePic/04/profileSmall.jpg"
},
{
"title": "Great deals and prices",
"body": "I found exactly what I was looking for, Thanks!",
"how_old": "1 month ago",
"total_comments": 1,
"date": "2011-08-27 15:22:32",
"review_url": "http://www.goodpickle.com/site/review/great-deals-and-prices-100",
"location": "Location X",
"media_type": "signature",
"media_src": "http://www.goodpickle.com/media/signatures/98_100/signature100.jpg",
"reviewer_url": "http://www.goodpickle.com/memberProfile/33",
"reviewer_name": "Jane Doe",
"reviewer_pic": "http://www.goodpickle.com/media/profilePic/33/profileSmall.jpg",
"member_url": "http://www.goodpickle.com/XYZ",
"member_name": "Company XYZ",
"member_pic": "http://www.goodpickle.com/media/profilePic/04/profileSmall.jpg"
}
]
}
}
getProfileStats
Description: Retrieve profile statistics in a given date range, including number of testimnoial, comments, and page views.
Parameters:
Name
Description
Default Value
Required
api_key
Your developer API key
(NONE)
Required
format
The format of the returned data. Valid values are "json" and "xml"
json
Optional
callback
The name of your javascript callback function. If you include this parameter, the results will be returned as JSONP, calling your function with a results object as the first parameter. Note: this will not do anything if you specify the 'format' parameter as xml.
(NONE)
Optional
start_date
Beginning date of the date range, in 'YYYY-mm-dd' format
Monday of the current week
Optional
end_date
End date of the date range, in 'YYYY-mm-dd' format
Current Day
Optional
Example request:
http://api.goodpickle.com/getProfileStats?api_key=YOUR_API_KEY&format=json&start_date=2011-01-01&end_date=2011-05-15
Example response:
{
"results": {
"status": "OK",
"start_date": "2011-01-01",
"end_date": "2011-05-15",
"num_reviews": "37",
"num_comments": "23",
"num_views": "1307"
}
}
getCounts
Description: Retrieve number of pending testimonials, approved testimonials, pending comments, and unread mail.
Parameters:
Name
Description
Default Value
Required
api_key
Your developer API key
(NONE)
Required
format
The format of the returned data. Valid values are "json" and "xml"
json
Optional
callback
The name of your javascript callback function. If you include this parameter, the results will be returned as JSONP, calling your function with a results object as the first parameter. Note: this will not do anything if you specify the 'format' parameter as xml.
(NONE)
Optional
type
The type of count you would like to retrieve. Possible values are 'all', 'pendingTestimonials', 'receivedTestimonials', 'pendingComments', and 'unreadMail'
all
Optional
Example request:
http://api.goodpickle.com/getCounts?api_key=YOUR_API_KEY&format=xml&type=all
Example response:
{
"results": {
"status": "OK",
"count_type": "all",
"pending_testimonial_count": "2",
"received_testimonial_count": "67",
"pending_comment_count": "5",
"unread_mail_count": "1"
}
}
Code Examples
PHP Example
<?php
//Sample API Call to getTestimonialsReceived Method
//Setup Params
$params = array('api_key' => 'YOUR_API_KEY',
'type' => 'scan',
'format' => 'json',
'items' => 5);
//Call the method
$data = file_get_contents("http://api.goodpickle.com/getTestimonialsReceived&".http_build_query($params));
//Process Results
$data = json_decode($data);
if($data->results->status == 'OK') {
//loop through testimonials and do something with the data
foreach($data->results->testimonials as $testimonial) {
;
}
} else {
//capture the error if the method call failed
$error = $data->results->status;
}
?>
Javascript Example (JSONP)
<!-- Example javascript call to getProfileStats method -->
<script type="text/javascript">
function processResults(data) {
if(data.results.status == 'OK') {
//access the data here
} else {
//log the error
console.log('Error: ' + data.results.status);
}
}
</script>
<!-- Be sure to include the name of your function as the 'callback' parameter -->
<script type="text/javascript" src="http://api.goodpickle.com/getProfileStats?api_key=YOUR_API_KEY&format=json&start_date=2011-01-01&end_date=2011-05-15&callback=processResults"></script>
Javascript Example (JSONP with jQuery)
<!-- Example javascript call to getCounts method using jQuery -->
<script type="text/javascript">
$(document).ready(function() {
$.getJSON('http://api.goodpickle.com/getCounts&api_key=YOUR_API_KEY&callback=?',function(data) {
if(data.results.status == 'OK') {
//access the data here
} else {
//log the error
console.log('Error: ' + data.results.status);
}
});
});
</script>
comments powered by Disqus