Using the Poutsch API

Using the Poutsch API, you can build applications that take questions and opinions on the web to the next level.

With this guide we explain and provide code examples for many common integration use cases like asking and voting on Poutsch questions or following users and tags. You will also be able to take advantage of many social features we offer on Poutsch such as comments, notifications and opimatches.

All you need to have in mind is that we play around with three major types of ressources:

Users: A Poutsch user can ask and answer questions, he can even comment them. When he starts to follow a tag or another user, he will get the related questions and opinions in his feed. His influence is visible on his dashboard and his opinion compatibility with other users is shown through an opimatch.

Questions: There are four types of questions on Poutsch (binary, multiple, slider and rating) and they all return quantitative data that can be sourced using the API.

Tags: They describe the questions they are attached to and allow us to create dynamic lists of questions around specific topics like « obama » or « fashion ».
Users can follow them so every tag consist of a list of followers in addition to the list of questions they correspond to.

Now go ahead and jump to the section you're most interested in and get started ! If you get stuck, drop us a line at developers@poutsch.com

Endpoints and Versions

Each endpoints is accessible on the following URL by replacing ENDPOINT:

https://poutsch.com/api/v1/ENDPOINT

An example to get a question:
TRY

https://poutsch.com/api/v1/questions/10001234

Structure and Envelope

Every response is contained by an envelope.

{"meta" : "404",  "response" : { "value1" : "here comes the data", "value2" : "here comes the data"}, "error":{
  "name":"Not found",
  "details":"No such Question"
}}

Meta contains the http response code which is described here. The error_details variable displays a human readable message.

Scope display test

endpoint	ask	profile	friends
/users/me
/users/:id

JSONP

In the case you want to use our response with a JS callback, you can pass your callback name.

https://poutsch.com/api/v1/.../?callback=callbackFunction

Would response with

callbackFunction({  ... enveloppe goes here  });

Errors

For more infomation on how to handle errors, the codes and the meta codes click here

Authentification

Before playing with the API, there are a few steps to deal with.

The Poutsch REST API uses OAuth 2.0 to secure the accesses.
The main goal of OAuth is to let Poutsch server authentify users. Applications don't handle the authentification, they just redirect users to Poutsch Authentification server.

How does it work?

To use the API, you need an access token. You will have to join this token to any of your requests to be authorized to use an user's data.
Some requests don't need authentification. If you only want to use "free" requests, please ignore the following procedure.

Access token obtention

The grant flow is pretty simple. Here are the different steps to obtain an access token:

Redirect the user to the Poutsch Authentification server. Here he will be asked to grant access to his data. If user accepts, you will obtain an authorization code.
With this authorization code, you can now ask to the Authorization server an access token thanks to your app_id and app_secret.
If your credentials (app_id and app_secret) are good, the Authorization server will return you the access token.

But to begin, you need to obtain your credentials. Simply go to this page, and create a new application.

Step 1: get user approbation

Ok, you've got your application id (app_id) and your application secret? Great, we can move on.
In this step, you will redirect the user to the Poutsch service in order to get his agreement to use his data.

Typically this can be done with a redirection, a popup, or a link "connect".

The redirection

The URL to contact is:

https://poutsch.com/authorize?response_type=code&app_id=MY_APP_ID&state=MY_STATE&scope=SCOPE1%20SCOPE2

You have to replace MY_APP_ID by the app id (app_id) by the one we gave you in step 1.
MY_STATE can be anything, it's for you and your application. When we will contact your server via the redirect_url, we will send you back the state argument.
The scope parameter represents the scopes that your application requires space separated. In other terms, it's the different actions your app will be able to do on the user behalf.
For each endpoint in this documentation, the scope needed is indicated. We highly recommand you to ask for the less scopes possible.
The less scopes you ask, the more chance you will have to get user acceptance.

User approval

Once the user will be on this page, he will have, if unlogged to log in, and to accept your application and the scopes required.
The acceptation done, user will be redirected to the url you indicated at "Redirect URL".

URL redirection

We will call the "Redirect URL" with a few parameters :

	http://www.mytestwebsite.com/?state=MY_STATE&code=4164662847c002786e5b9327eae9c231e6651d05

As promised, you have your state back for your personal use. We also added a code called authorization code.
This code doesn't allow you yet to access to the API. This code says: "user X is OK that the app accesses to his data".

If user refused to accept your application, your url will have instead of a code, an error :

	http://www.mytestwebsite.com/?state=MY_STATE&error=access_denied

The next step, is the final one. You have to send back this code to the server in order to prove that you are who you pretend to are.
Time to reveal your secret!

Step 2: Validate your identity

You have in your hands the authorization code. This code just says that the user is OK that you act on his behalf.
The next step is to ask to Poutsch the access token, thanks to your secret and your authorization code.

Asking for an access token

The url to contact is:

https://poutsch.com/api/v1/oauth/access_token

Parameters

Parameters	Value	Description
grant_type required	authorization_code	The grant type. Always "authorization_code" in this case.
app_id required		Your app ID that Poutsch gave you during registration
app_secret required		Your app secret that Poutsch gave you during registration
code required		The authorization_code Poutsch gave you at step 1

Examples

You can see different examples here: PHP

Response

If you see the next response, congratulations, you're now allowed to use the API!
Be sure to keep these information confidential.

{"access_token":"81485e011387cd7a719e6e03654498413801e795","expires_in":3600,"token_type":"bearer","scope":"","refresh_token":"ff91c6cfea6b2e5f7b222b5001e2daed8d80a7f9"}

Variable	Description
access_token	The grail we were looking for. With this token, you now have access to the API (how? See next step)
expires_in	For security reasons, the access tokens expire often, and you must renew them (how? See next step !). This is the expiration time in seconds.
token_type	The token type you've received, in our case, it will be bearer.
scope	The scopes that were allowed for your apps. Be sure to check that they fit with the ones you've asked!
refresh_token	When your access token expires, you can renew it thanks to the refresh token.

Let's meet at next step to see what we can do with these tokens.

Step 3: Get access to the API

You now have your access token, you can now access to the API.
Simply browse the different endpoints described in this documentation, and add your access token with a GET parameter.

Example

To get the information about the user with uid=3, let's try this:

https://poutsch.com/api/v1/users/3?access_token=YOUR_ACCESS_TOKEN

Renewing the token

After a short time, your access token will expire. You have to renew it thanks to the refresh token of step 3.
As you did at step3, query Poutsch server:

https://poutsch.com/api/v1/oauth/access_token

Parameters

Parameters	Value	Description
grant_type required	refresh_token	The grant_type. Always "refresh_token" in this case.
app_id required		Your app ID that Poutsch gave you during registration
app_secret required		Your app secret that Poutsch gave you during registration
refresh_token required		The refresh_token Poutsch gave you at step 2

You will get the same response than if you had asked for an access token.

Introduction to references

The Poutsch API exposes Poutsch resources like questions, tags and users. These resources can be accessed and manipulated using the HTTP methods GET, POST, PUT and DELETE.

All Poutsch resources are accessed and manipulated in a similar way. A list of the latest resource is usually available through /[resource name], a single specific resource through/[resource name][id] and related subresources like opinions through/[resource name]/[id]/[subresource name].

Resources are returned as JSON by default. Unless otherwise specified, the base URL for API endpoints is:

https://poutsch.com/api/v1/endpoint

To access public resources you just have to pass a app_id parameter:

To be continued...

To act on behalf of a Poutsch user, they must first authenticate your app.

GET users/me

Description

Returns the information about the currently logged-in user.

HTTP Method	GET
Authentification required	Yes

Parameters

Parameters	Options	Default	Description
details optional	full mini	mini	Exists in two formats, mini is a condensed one.

Response

You can find more information about return variables on this page.

Scope

profile_info neccesary to display full profile

Parameters	Options	Default	Description
limit optional	integer	20	Number of results to fetch. (Max 20)
offset optional	integer	0	Number of results to skip before fetching.

Parameters	Options	Default	Description
limit optional	integer	20	Number of questions to fetch. (Max 20)
offset optional	integer	0	Number of questions to skip before fetching.
local optional	country city region		You can get, thanks to your geolocalisation, questions asked in your country, city, or region.

Parameters	Options	Default	Description
id required	integer	none	The unique user ID
details optional	full mini	mini	Exists in two formats, mini is a condensed one.

Parameters	Options	Default	Description
limit optional	integer	10	Number of notifications to fetch.
offset optional	integer	0	Number of notifications to skip before fetching.

Variable name	Description
name	The choice name
index	The index of the answer. This integer allows to identify each choice of the question and is used for the vote the multiple and binary questions. For numbers and stars questions, this variable isn't displayed.
percentage	The percentage of users who picked this choice for this answer.
votes	The number of votes for this choice
following	An Array containing the basic information about the users you follow and who have answered the question.
following_extra	The number of users you follow but who haven't been described in the array following (cf NB)

Parameters	Options	Default	Description
question_type required	binary multiple number stars	none	Defines the type of the posted question
question required	String	none	The posted question. 120 characters max
tags optional	String	none	Tags affiliated at the question, coma separated. tag1,tag2,tag3,tag4
upload_file optional	String	none	Upload a picture
file_url optional	String	none	An URL to a picture
link optional	String	none	A link that expresses the context of the question. Video, website...

Parameters	Options	Default	Description
accuracy optional	integer	0	Decimal accuracy If accuracy is equal to 0, choices will be integers, if accuracy is equal to 1, choices will be floats with 1 digit.
min optional		0	Minimum choice
max optional		100	Maximum choice
unit optional	string	units	Represents the unit
unit_type optional	unit_type	Other	Type of unit

Variable name	Description
comment_vote	Indicates if the user has voted or no. Always false if not logged in.
id	The unique comment id.
can_edit	Can user edit the comment? (false or true)
comment	The comment.
user	The User as described in users mini format.
date	The date when the comment was posted All dates respect the format, "Sat, 21 Aug 2010 22:31:20 +0000", which can be used with strftime or strptime: %a, %d %b %Y %H:%M:%S %z
score	The score of the comment (upvotes - downvotes)
replies	An array contening the replies to the comment. The format is the same than the one described here, except that replies aren't editable and don't include any reply.

Unit type	Unit example
percentage	30%, 40%...
length	meters, centimeters, kilometers, milimetters, miles, yards, feet, inches, lightyears...
area	square meters, hectares, acres, square km, square miles...
volume	liters, milliliters, cubic meters, cubic feet, gallons, fluid, once, teaspoon, tablespoon...
mass	kilograms, grams, milligrams, tonnes, pounds, eV...
currency	EUR, USD...
time	seconds, minutes, hours, days, weeks, months, years...
temperature	celsius, fharenheit, kelvin...
other	carots, tomatoes, space rockets...

	full	mini	description
id			User ID (UID) - a number assigned to each user
username			Unique user name - user pages are available at poutsch.com/user/:username
level			The level in Poutsch - calculated with: opinions, collected opinions and followers
picture_url			A link to the user avatar. If not provided by user, the default picture will be returned
tag_line			A personnal status
full_name			Name of the user
total_following			Total number of people that user follows
total_followers			Total number of people who follow the user
total_questions			Total number of questions asked
total_opinions			Total number of questions answered
birthday			The birthday of the user, can be in format YYYY-MM-DD / MM - DD / YYYY
country			The country where the user lives in
following			Boolean, are you following the user or not.
link_facebook			The link to the user facebook account
link_twitter			The link to the user twitter account

variable	description
qid	Question ID - a number assigned to each question
author_id	The id (UID) of the user who published the question
author_username	The username of the user who published the question
question	The question
type	Question type : binary - multiple - number - stars
choices	The different choices available for the question
total_votes	The number of users who responded to the question
user_vote	The user response
tags	The tags affiliated to this question. tags[tid] = tag_name
date	The date of publication of the question. All dates respect the format, "Sat, 21 Aug 2010 22:31:20 +0000", which can be used with strftime or strptime: %a, %d %b %Y %H:%M:%S %z
total_comments	The total of comments for the question
total_changes	The total number of opinion modification
total_unique_changes	The total number of users who modified their opinion
upload_file	A file field containing a picture (JPEG, PNG, or GIF)
file_url	A link to an url picture (JPEG, PNG or GIF)
author_picture	The link to the question author picture
video	Link to the video

variable	description
unit_type	The unit type as described here
unit	The unit
min	The minimum allowed value for the answer
max	The maximum allowed value for the answer
accuracy	Decimal accuracy If accuracy is equal to 0, choices will be integers, if accuracy is equal to 1, choices will be floats with 1 digit.

endpoint	variable	description
GET users/me/explore	total_7days	This variable represents the total of votes during the last 7 days.
GET users/:id/opinions	anonymous	It tells if the user answered anonymously or not. This variable is usefull only for the user himself.

variable	description
id	Tag ID - a number assigned to each tag
tag	The name of the tag
total_questions	The number of questions affiliated a this tag
total_followers	The number of user who follow this tag

	description
nid	Notification ID (NID) - a number assigned to each notification
notif_type	The type of the notification. Can be: new_vote An user has responded to one of your questions. new_follower A new user is following you. new_level You have won a level. new_comment An user has commented one of your questions. new_tag A user has mentioned you in a comment. new_message You've got a new message in your inbox.
date	The date when the notifications was thrown. All dates respect the format, "Sat, 21 Aug 2010 22:31:20 +0000", which can be used with strftime or strptime: %a, %d %b %Y %H:%M:%S %z
qid	The unique question id (QID), only displayed if the notification is linked to a question.
question	The question, only displayed if the notification is linked to a question.
user	The user, as described in users attributes page.
more	Sometimes notifications can be grouped in one (e.g. if 15 users answer to one of your question, you will just have one notification). The "more" variable is the number of notifications that have been grouped with the first one (in this example, more will be equal to 14).
ago	A human readeable message indicating how long ago the notifications was thrown.

variable	description
id	Comment ID - a number assigned to each comment or reply
comment_vote	Has user voted on the comment? (boolean true/false)
can_edit	Can user edit the comment? (boolean true/false)
comment	The comment
reply	The reply
user	The user who posted the comment or reply, you can find more information here
date	The date of publication of the question. All dates respect the format, "Sat, 21 Aug 2010 22:31:20 +0000", which can be used with strftime or strptime: %a, %d %b %Y %H:%M:%S %z

	full	mini	description
id			Group ID (GID) - a number assigned to each group
name			Unique group name
creator			The creator, as described in users attributes page.
summary			A summary of the group
description			A description of the group
website			A website related to the group
invite_control			Boolean. Is group public or semi-private?
date			The date when the group was created. All dates respect the format, "Sat, 21 Aug 2010 22:31:20 +0000", which can be used with strftime or strptime: %a, %d %b %Y %H:%M:%S %z
users_total			Total of users in the group.

Parameters	Options	Default	Description
name required	String	none	Defines the name of the group
summary required	String	none	The summary of the group
description required	String	none	A short description of the group
website optional	String		A website related to the group
invite_control optional	Boolean	false	If true, the admins of the group will have to accept join requests

Parameters	Options	Default	Description
limit optional	integer	10	Number of users to fetch.
offset optional	integer	0	Number of users to skip before fetching.

HTTP code	Name	Description
200	Ok	Normal return code, when everything went well.
204	No Content	No error occured, but the server doesn't have data to return.
400	Bad Request	The request is not well written, you should check the parameters of the request.
401	Unauthorized	This error occurs when there is a problem with your authentification. Check your access tokens.
403	Forbidden	You're well logged into the API, but you don't have access to this information (you can't really do something here ;-))
404	Not Found	The ressource you're trying to access, such as a user, doesn't exist.
500	Internal Server Error	Something went wrong in Poutsch service. Please contact us so we can fix it.
503	Service Unavailable	The request couldn't be processed by the server. Please try again later.

Using the API

API references

APP Examples

Using the Poutsch API

Endpoints and Versions

Structure and Envelope

Scope display test

JSONP

Errors

Authentification

How does it work?

Access token obtention

Step 1: get user approbation

The redirection

User approval

URL redirection

Step 2: Validate your identity

Asking for an access token

Parameters

Examples

Response

Step 3: Get access to the API

Example

Renewing the token

Parameters

Introduction to references

GET users/me

Description

Parameters

Response

Scope

Request example

GET users/me/feed

Description

Parameters

Response

Scope

Request example

GET users/me/explore

Description

Parameters

Response

Scope

Request example

GET users/:id

Description

Parameters

Response

Scope

Request example

GET users/:id/tags

Description

Parameters

Response

Scope

Request example

GET users/:id/questions

Description

Parameters

Response

Scope

Request example

GET users/:id/opinions

Description:

Parameters

Response

Scope

Request example

GET users/:id/following

Description

Parameters

Response

Scope

Request example

GET users/:id/followers

Description

Parameters

Response

Scope

Request example