Integrating CircleMe in your own app allows you to add personalization and gather insight into the passions of your user, which in turn can help you in providing a better experience and higher value.
The CircleMe API (preview as of 2014-12-01) allows you to access
To be able to access this data and in order to guarantee a user's privacy, you need to obtain a token
via the standard OAuth2 protocol, which requires you to register an application.
You can find the link to Api Management in your settings page after you have
been accepted in the program.
During the developer preview the program is only available to selected users, if you want to try it out you can write to partnerships@circleme.com. We'll get back to you as soon as possible.
Once you have obtained a pair of App Id and App Secret you can setup your OAuth2 client using the "site"
https://www.circleme.com
with the callbacks paths at /oauth/authorize
and
/oauth/token
.
The scope you should be requesting is basic_info
, which is the default for OAuth2.
The API endpoints return simple json structures, and are namespaced by the api version.
All results are relative to the user identified by the current OAuth2 token, which means you
need a token for each new user
.
The current preview all refers to the base url https://api.circleme.com/v201410/
.
All endpoints are accessible via GET and where appropriate take a limit
and offset
parameters.
You can send the access_token
to the server through either the HTTP_AUTHORIZATION
header or the access_token
query parameter.
We suggest you use an OAuth2 client library that will handle this for you rather than rolling your own.
The current endpoint together with sample output are listed in the following table
Description | HTTP Method | PATH | optional params | sample response |
---|---|---|---|---|
Basic user profile info | GET | /v201410/me.json |
{ "id": 987121, "name": "Joe", "surname": "Smith", "username": "KewlName", "fullname": "Joe Smith", "avatar": "http://a.url.to.a.picture.com/avatar.jpeg?1399400872" } |
|
List of Like'd interests, most recent first. You can paginate by using the limit and offset params. | GET | /v201410/liked.json?offset=0&limit=100 |
limit = 100..400, default 100
offset = default 0 |
[{"path":"/items/ally-mcbeal","name":"Ally McBeal","category":"movie"},{"path":"/items/lady-gaga--3","name":"Lady Gaga","category":"music"},...,{"path":"/items/blade-runner--11","name":"Blade Runner","category":"movie"}] |
List of ToDo'd interests, most recent first. You can paginate by using the limit and offset params. | GET | /v201410/tobedone.json?offset=0&limit=100 |
limit = 100..400, default 100
offset = default 0 |
[{"path":"/items/ally-mcbeal","name":"Ally McBeal","category":"movie"},{"path":"/items/lady-gaga--3","name":"Lady Gaga","category":"music"},...,{"path":"/items/blade-runner--11","name":"Blade Runner","category":"movie"}] |
List of Upcoming events for this user. These are sorted by distance and time and relative to the last user location (based on signup data). | GET | /v201410/next_events.json |
[ { "summary": "Concert Katy Perry", "event_type": "Concert", "start_at": "2015-02-24T20:00:00Z", "location_name": "Krakow, Poland" }, { "summary": "Festival Muse", "event_type": "Festival", "start_at": "2015-06-04T14:00:00Z", "location_name": "Vienna, Austria" } ] |
If the API calls succeed you should always receive a 200
status code
If you fail to authenticate you will receive a 422
response or other
4xx
error codes.
If the server errors out you might get 5xx
error.
When errors occur, especially if you are not authenticated, the response will not in general be encoded
as JSON (i.e. you might get an HTML page), thus you should structure your code like
response = get(url) if response.success JSON.parse(response.body) else print "something bad occurred, look at response headers and body" end
Any OAuth2 example for your platform/language should be ok,
but we wrote a couple of CircleMe specific examples so you can take inspiration.
If you need help or donif you have some other open source code you want to share with the world, and want it featured here, just write us.
A reference image for a CircleMe link is the following
which you can use as![]()
<a href="https://your.domain/oauth/callback"><img src="https://pcdn0.circleme.com/assets/api/connect-7d4e979a60d6acd938d01d7f037c312cbefe4e67dca86b36863c4335a8abf5dd.png" /></a>Our standard color "circleme red" in CSS is #E44142.
Please refer to our terms of service and privacy policy