Thanks for checking out the new OneTrueFan API. If you build something cool using the API, be sure to ping @onetruefan us on Twitter to let us know. Also tell us anything you would like to see us add -- this is truly a Beta API at this point. Cheers!
Site based requests are useful for pulling site specific information, such as recent shares, checkins, fans, related trending pages and sites, and user-site relationships.
Retrieve site information, including the One True Fan user object.
(request) http://api.onetruefan.com/v1/site/mashable.com
{
"id":"mashable.com",
"favicon":"http:\/\/i3.onetruefan.com\/favicons\/2917.png",
"fans":92483,
"title":"Social Media News and Web Tips - Mashable - The Social Media Guide",
"url":"http:\/\/mashable.com",
"onetruefan": { ... }
}
Retrieve the One True Fan of a site.
Returns a user object.
(request) http://api.onetruefan.com/v1/site/mashable.com/onetruefan
{
"id":"emisare",
"name":"emisare",
"image":"http:\/\/a1.twimg.com\/profile_images\/120419460\/Emisare_E_normal.jpg",
"location":"Greensboro, NC 27406",
"gender":"m",
"age":"45",
"url":"http:\/\/www.emisare.com",
"services":{
"twitter":"http:\/\/twitter.com\/emisare",
"facebook":"http:\/\/www.facebook.com\/profile.php?id=697286658"
}
}
Retrieve recent site checkins.
Returns a list of checkins, including the related page and user objects.
(request) http://api.onetruefan.com/v1/site/mashable.com/recent/checkins
[
{"timestamp":"2021-06-14 18:01:07", "page":{ ... }, "user":{ ... }},
{"timestamp":"2021-06-14 18:01:08", "page":{ ... }, "user":{ ... }},
...
]
Retrieve recent site shares.
Returns a list of shares, including the related page and user objects.
(request) http://api.onetruefan.com/v1/site/mashable.com/recent/shares
[
{"timestamp":"2021-06-14 18:01:07", "page":{ ... }, "user":{ ... }},
{"timestamp":"2021-06-14 18:01:08", "page":{ ... }, "user":{ ... }},
...
]
Retrieve the top fans of a site.
Returns a list of users, including their site score.
(request) http://api.onetruefan.com/v1/site/mashable.com/top/fans
[
{
"id":"emisare",
"name":"emisare",
"image":"http:\/\/a1.twimg.com\/profile_images\/120419460\/Emisare_E_normal.jpg",
"location":"Greensboro, NC 27406",
"gender":"m",
"age":"45",
"url":"http:\/\/www.emisare.com",
"services":{
"twitter":"http:\/\/twitter.com\/emisare",
"facebook":"http:\/\/www.facebook.com\/profile.php?id=697286658"
},
"score":669
},
...
]
Retrieve the top pages of a site.
Returns a list of pages, including their site score.
(request) http://api.onetruefan.com/v1/site/mashable.com/top/pages
[
{
"id":"05724f561b8887ca1262fe5ce608cc8e",
"title":"Apple Starts Selling Unlocked iPhone 4 in the U.S.",
"url":"http:\/\/mashable.com\/2011\/06\/14\/unlocked-iphone\/",
"score":993
},
{
"id":"5de0a5a65af6fafcd60489cf2bc85cef",
"title":"Comcast Is Bringing Skype to TV",
"url":"http:\/\/mashable.com\/2011\/06\/14\/comcast-skype\/",
"score":711
},
...
]
Retrieve pages that are trending on other sites with this site's fans.
Returns a list of pages, including their trending score.
(request) http://api.onetruefan.com/v1/site/mashable.com/trending/pages
[
{
"id":"794b6013dc7c5d480ba225f749eb0504",
"title":"Why Groupon Is Poised For Collapse",
"url":"http:\/\/techcrunch.com\/2011\/06\/13\/ ... \/",
"score":627
},
{
"id":"df1389b5d2d0bbfd874694e088c11528",
"title":"The Future of Social Media",
"url":"http:\/\/thenextweb.com\/socialmedia\/2011\/ ... \/",
"score":254
},
...
]
Retrieve sites that are trending with this site's fans.
Returns a list of sites, including their trending score.
(request) http://api.onetruefan.com/v1/site/mashable.com/trending/sites
[
{
"id":"221",
"favicon":"http:\/\/i1.onetruefan.com\/favicons\/221.png",
"fans":64990,
"title":"TechCrunch",
"url":"http:\/\/techcrunch.com",
"score":3132
},
{
"id":"801",
"favicon":"http:\/\/i3.onetruefan.com\/favicons\/801.png",
"fans":40306,
"title":"The Next Web | TNW is the International ...",
"url":"http:\/\/thenextweb.com",
"score":2003
},
...
]
Retrieve user-site relationship information.
Returns a user object, including their site score, patches and shares of the site.
(request) http://api.onetruefan.com/v1/site/mashable.com/user/toddsampson
{
"id":"toddsampson",
"name":"Todd Sampson",
"image":"http:\/\/a0.twimg.com\/profile_images\/919737038\/ ... jpg",
"location":"San Francisco, CA, US",
"gender":"m",
"age":"37",
"url":"http:\/\/www.toddsampson.com",
"services":{
"twitter":"http:\/\/twitter.com\/toddsampson",
"facebook":"http:\/\/www.facebook.com\/profile.php?id=719837985"
},
"score":66,
"patches":[
{"timestamp":"2021-11-14 03:13:31", "patch":{ ... }},
{"timestamp":"2021-11-14 03:14:16", "patch":{ ... }},
...
],
"shares":[
{"timestamp":"2021-09-15 10:59:40", "page": { ... }},
{"timestamp":"2021-09-16 05:50:20", "page": { ... }},
...
]
}
Page based requests allow you to gain insight at the page level. This includes basic information, recent shares, recent checkins and also recommendations based on fans of the page.
Lookup a page by URL.
Returns a page object.
(request) http://api.onetruefan.com/v1/page/lookup?url=http://mashable.com/2011/06/14/pandora-ipo-wednesday-2/
{
"id":"fe7d77f79c4ab48a4cdb7f9cd6c66b90",
"title":"Pandora Media IPO Set for Wednesday",
"url":"http:\/\/mashable.com\/2011\/06\/14\/pandora-ipo-wednesday-2\/",
"site":"mashable.com"
}
Return a random page.
Returns a page object.
(request) http://api.onetruefan.com/v1/page/random
{
"id":"aa678b7c97a8662126b201bfbc9a938c",
"title":"Stun Belt OK'd for Ariz. Inmate with Escape Charge",
"url":"http:\/\/www.myfoxphoenix.com\/dpp\/news\/justice\/ ..."
}
Retrieve page information.
Returns a page object.
(request) http://api.onetruefan.com/v1/page/fe7d77f79c4ab48a4cdb7f9cd6c66b90
{
"id":"fe7d77f79c4ab48a4cdb7f9cd6c66b90",
"title":"Pandora Media IPO Set for Wednesday",
"url":"http:\/\/mashable.com\/2011\/06\/14\/pandora-ipo-wednesday-2\/",
"site":"mashable.com"
}
Retrieve a page recommendation, based on the provided page.
Returns an object containing the recommended page, the most recent user recommendation and the total number of recommendations.
(request) http://api.onetruefan.com/v1/page/fe7d77f79c4ab48a4cdb7f9cd6c66b90/recommended
{
"page":{
"id":"6af483838acde20bb52e70ab7651717e",
"title":"USA Network's Covert Affairs Launches Alternative Plotline on Twitter",
"url":"http:\/\/mashable.com\/2011\/06\/14\/covert-affairs-twitter\/"
},
"recommended_by":{
"user":{ ... },
"total":295
}
}
Retrieve recent checkins of a page.
Returns a list of checkins, including associated user object.
(request) http://api.onetruefan.com/v1/page/fa6cfa0cb03c3b19ae84e05ea5ec5305/recent/checkins
[
{"timestamp":"2021-06-14 18:01:07", "user":{ ... }},
{"timestamp":"2021-06-14 18:01:08", "user":{ ... }},
...
]
Retrieve recent sharers of a page.
Returns a list of sharers, including associated user object.
(request) http://api.onetruefan.com/v1/page/fa6cfa0cb03c3b19ae84e05ea5ec5305/recent/shares
[
{"timestamp":"2021-06-14 17:20:01", "user":{ ... }},
{"timestamp":"2021-06-14 17:38:10", "user":{ ... }},
...
]
User based requests allow you to retrieve user specific information, including One True Fans, patches and shares.
Retrieve user information.
Returns a user object.
(request) http://api.onetruefan.com/v1/user/toddsampson
{
"id":"toddsampson",
"name":"Todd Sampson",
"image":"http:\/\/a0.twimg.com\/profile_images\/919737038\/ ... jpg",
"location":"San Francisco, CA, US",
"gender":"m",
"age":"37",
"url":"http:\/\/www.toddsampson.com",
"services":{
"twitter":"http:\/\/twitter.com\/toddsampson",
"facebook":"http:\/\/www.facebook.com\/profile.php?id=719837985"
}
}
Retrieve a user's One True Fans.
Returns a list of site objects.
(request) http://api.onetruefan.com/v1/user/steveho/onetruefans
[
{
"id":"2489",
"favicon":"http:\/\/i1.onetruefan.com\/favicons\/2489.png",
"fans":56514,
"title":"Business Insider",
"url":"http:\/\/businessinsider.com"
},
...
]
Retrieve a user's patches
Returns a list of patches, including associated site information.
(request) http://api.onetruefan.com/v1/user/steveho/patches
[
{"timestamp":"2021-05-26 19:18:25", "patch":{ ... }, "site": "techmeme.com"},
{"timestamp":"2022-02-01 22:20:01", "patch":{ ... }, "site": "businessinsider.com"},
...
]
Retrieve a user's recent shares
Returns a list of recent shares, including associated page information.
(request) http://api.onetruefan.com/v1/user/steveho/shares
[
{"timestamp":"2021-06-02 19:18:25", "page":{ ... }},
{"timestamp":"2021-06-01 22:20:01", "page":{ ... }},
...
]
Retrieve a user's fanned sites.
Returns a list of sites, including the user's site score.
(request) http://api.onetruefan.com/v1/user/steveho/sites
[
{
"id":"1",
"favicon":"http:\/\/i2.onetruefan.com\/favicons\/default.png",
"fans":4,
"title":"Untitled",
"url":"http:\/\/onetruefan.dev",
"score":120
},
...
]
When running the OneTrueFan Widget on your site, there is additional data available after the widget loads that can help you build experiences unique to your readers.
The username of the currently authorized user viewing the page that loaded the widget.
This can be used to query against the API and grab information about the user who is currently looking at the page. Here is a simple example of using the username to lookup the currently authorized user by sending this data to the server (using jQuery), doing a lookup (PHP) and returning the result.
Client Side:
$.get('/lookup.php?username=' + OneTrueFan.Data.login, function(user) {
// user information can be used here
}, 'json');
Server Side:
echo file_get_contents('http://api.onetruefan.com/v1/user/' . $_GET['username']);
The id of the page that loaded the widget.
This can be used to query against the API and grab page specific information, including users who have shared the page and recently checked in. Here is a simple example of using the page_id to lookup recently checked in users by sending this data to the server (using jQuery), doing a lookup (PHP) and returning the result.
Client Side:
$.get('/lookup.php?page_id=' + OneTrueFan.Data.page_id, function(users) {
// users can be used here
}, 'json');
Server Side:
echo file_get_contents('http://api.onetruefan.com/v1/page/' . $_GET['page_id'] . '/recent/checkins');