Using the CircleMe API & CircleMe Link

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

a user's profile (id, name, surname, username, fullname, and avatar)
a user's Liked items (path, name, and category)
a user's ToDo items (path, name, and category)
a user's upcoming events (summary, event_type, start_at, and location_name)

Applying for the CircleMe Link Program

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.

Using the APIs

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" } ]

Notes on Response Codes

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

Sample Code

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.

Identity/Graphics/Style for Circleme Link

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://pcdn3.circleme.com/assets/api/connect-a71fa53208d544349d5205089f5da374.png" alt="Connect" /></a>

Our standard color "circleme red" in CSS is #E44142.

Legal

Please refer to our terms of service and privacy policy