API / Tech Specifications

Pitia is based on a REST API in order to make possible the integration of the Recommender System on almost any application with an internet connection.

Adding Classifications & Getting Back Recommendations

In order to send the classifications for a user and get back the recommendations your app has to perform a HTTP POST request to the next URL:

http://api.pitia.info/rec

Sending the next parameters:
  • uid : User ID, the e-mail associated with the account
  • group : Group ID, the group identifier, is the one at the top of the corresponding group box in the "Management panel"
  • key : Group key, you can find this key in the "Management panel" inside the group box
  • insert (optional) : Specify this parameter using a "1" as value in case of you just want to add the classifications to the system in order to populate it, you will not get classifications back, this kind of query will count as an "insert request"
  • id : A numeric (uin64) unique identifier for the provided classifications on this request, this ID will be used to replace previous classifications in case of the same source has sent them before. Use a unique identifier is important in order to avoid biases caused by multiple similar classifications stored on the system from the same source.
    If your application uses alphanumeric identifiers for the users, you can use algorithms like CRC32 to obtain a numeric identifier from a string, you don't need to worry about collisions, in the case of a collision between two identifiers the old classifications will be overwritten
  • max_recs : The max number of classifications to be returned by the system on this query. The max allowed value for this parameter is 100
  • scores : Dictionary serialised as JSON that has to contain as key an uint64 (encoded as string) to be used as element unique identifier, and as value a uint8 in ordet to be used as score. The value of the score can go from 0 to "Max Score", the "Max Score" is a field that has to be specified during the group creation and can be find on your "Management panel" for each group
    Example:
    
    {
        "16384": 5,
        "12672": 2,
        "12299": 4,
        "15887": 1,
        "13081": 5,
        "12317": 5
    }



Request Example

Example of a request for classifications using CURL:

$> curl 'http://api.pitia.info/rec' -X POST\
    -d 'uid=user_id'\
    -d 'key=group_key'\
    -d 'group=group_name'\
    -d 'id=123'\
    -d 'scores={"16384": 5, "12672": 2, "12299": 4, "15887": 1}'\
    -d 'max_recs=10'

* Hostname was NOT found in DNS cache
*   Trying 91.121.181.125...
* Connected to api.pitia.info (91.121.181.125) port 80 (#0)
> POST /rec HTTP/1.1
> User-Agent: curl/7.37.1
> Host: api.pitia.info
> Accept: */*
> Content-Length: 183
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 183 out of 183 bytes
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Date: Sat, 18 Apr 2015 16:02:23 GMT
< Content-Length: 154
< Content-Type: text/plain; charset=utf-8
<
{
    "success": true,
    "stored_elements": 3998728,
    "reqs_sec": 1,
    "recs": [2862,571,10947,12317,10042,11089,15107,14621,15205,17157]
}
* Connection #0 to host api.pitia.info left intact

			



Server Response

The server will perform the security checks and if all is in order it will return a JSON like the next back:

{
    "success": true,
    "stored_elements": 3999914,
    "reqs_sec": 173,
    "recs": [15205,17157,2782,14691,11064,12317,10042,2862,10947,571]
}
Returned parameters:
  • success : Boolean value that indicates if the request had success
  • stored_elements : Current number of stored elements on the shard
  • reqs_sec : Current ratio of request on the shard that attended the request
  • * recs : Array of unique IDs of the elements recommended for this request based on the sent classifications
* If the shard doesn't contain enought parameters to provide recomendations (less than 100 classifications), the array "recs" can be empty and the "success" field will contain a false as value



Item Scores

Pitia calculate the average score for each item. This information can be retrieved performing an HTTP POST or GET request to the next URL:

http://api.pitia.info/scores

Sending the next parameters:
  • uid : User ID, the e-mail associated with the account
  • group : Group ID, the group identifier, is the one at the top of the corresponding group box in the "Management panel"
  • key : Group key, you can find this key in the "Management panel" inside the group box
  • items : Array of element IDs (uint64) serialised as JSON
    Example:
    
    [
    	8280,
    	14804,
    	13050,
    	8958,
    	13056,
    	15105,
    	15107,
    	17157
    ]



Request Example

Example of a request for scores using CURL:

$> curl 'http://api.pitia.info/scores' -X POST -v\
>     -d 'uid=user_id'\
>     -d 'key=group_key'\
>     -d 'group=group_name'\
>     -d 'items=[8280, 14804, 13050, 8958, 13056, 15105, 15107, 17157, 15110, 15114]'
* Hostname was NOT found in DNS cache
*   Trying 91.121.181.125...
* Connected to api.pitia.info (91.121.181.125) port 80 (#0)
> POST /scores HTTP/1.1
> User-Agent: curl/7.37.1
> Host: api.pitia.info
> Accept: */*
> Content-Length: 183
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 183 out of 183 bytes
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Date: Thu, 23 Apr 2015 22:19:02 GMT
< Content-Length: 357
< Content-Type: text/plain; charset=utf-8
<
{
	"success": true,
	"reqs_sec": 10,
	"stored_elements": 3997490,
	"scores": {"13050":3.362357669122572,"13056":3.2597173144876326,"14804":3.620833333333333,"15105":3.6192536506219577,"15107":3.886912128712871,"15110":3.4806534823731727,"15114":3.7747440273037545,"17157":4.272283986736883,"8280":3.9027777777777777,"8958":4.015748031496063}
}
* Connection #0 to host api.pitia.info left intact

			



Server Response

The server will perform the security checks and if all is in order it will return a JSON like the next back:

{
	"success": true,
	"reqs_sec": 0,
	"stored_elements": 3997490,
	"scores": {"13050":3.362357669122572,"13056":3.2597173144876326,"14804":3.620833333333333,"15105":3.6192536506219577,"15107":3.886912128712871,"15110":3.4806534823731727,"15114":3.7747440273037545,"17157":4.272283986736883,"8280":3.9027777777777777,"8958":4.015748031496063}
}
Returned parameters:
  • success : Boolean value that indicates if the request had success
  • stored_elements : Current number of stored elements on the shard
  • reqs_sec : Current ratio of request on the shard that attended the request
  • scores : Dictionary where each key is the unique element ID and the value the average score for this element across the elements stored in memory



Error Codes

If there were an error, the server will respond according to the kind of it with one of the next codes:
  • 401 : Authentication error, check the "uid", key and group parameters
  • 429 : Too Many requests, the number of requests per second on the shard is bigger than the limit for this group
  • 400 : Bad Request, One of the sent parameters on the request is not valid, check the body response
  • 500 : Internal server error
  • 503 : All the shards are provisioning, there is no shard ready to attend this request