User needs API

The purpose of this article is to describe API endpoints for user needs tagging of provided articles.

API is designed to work asynchronously, schedule user needs tagging using URLs endpoint, which returns request id. Using that request, you check the status of tagging using the status endpoint and fetch results of tagging, if the request is successful using the user_needs endpoint.

Authentication

For authentication, api_key GET parameter should be set. Customer support should provide you with a valid key for authentication.

Example:

/api/brands/:brandId/user_needs/urls?api_key=xxxxxxxx

Endpoints

Content analysis

This way of usage implies the issuing an API call to /content endpoint, which in turn responds with detection results.

Content endpoint

This is a JSON POST endpoint

 

Endpoint path:

/api/brands/:brandId/user_needs/content

:brandId parameter is the id of your brand

 

JSON request payload example:

{

 "content":  "article full text"

}

 

URL object properties used to create request:  

**content** - mandatory value

 

JSON response example:

{

   "request_id": 2,

   "request_status": "COMPLETED",

   "user_needs": {

     "action_driven": true,

     "context_driven": true,

     "emotion_driven": false,

     "fact_driven": true

   }

}

URL analysis

This way of usage follows a three-step process:

 

  • Call /urls endpoint and pass URL/s to be analyzed. This call would return request_id which you would use in subsequent API calls
  • Call /status endpoint on a periodic base (ex. every ten seconds) passing the request_id to check the status of the request until you receive a COMPLETED status for you request
  • Once the status of your request is completed, call a /user_needs endpoint passing the original request_id to fetch results

Urls endpoint

This is a JSON POST endpoint

Endpoint path:

 

/api/brands/:brandId/user_needs/urls

:brandId parameter is the id of your brand

JSON request payload example:




URL object properties used to create request:  

**url** - mandatory value, url of article to be fetched (please make sure domain matches the domain configured for specified brandid)

 

JSON response example:

Example 1 

{

   "request_id": 1,

   "request_status": "PENDING"

}

 

Example 2

{

   "request_id": 1,

   "request_status": "COMPLETED",

   "user_needs":  [

       {

           "success": true,

           "article_url": "www.test.com/article/123456",

           "user_needs": {

               "action_driven": true,

               "context_driven": true,

               "emotion_driven": false,

               "fact_driven": true

        },

       {

           "success": false,

           "article_url": "www.test.com/4567"

       }

   ]

}

 

**user_needs** - is returned only if request is in status COMPLETED

 

List of possible statuses:

  • PENDING
  • COMPLETED
  • FAILED

 

Status endpoint

This is a GET endpoint

 

Endpoint path:

/api/brands/:brandId/user_needs/status/:request_id

:brandId parameter is the id of your brand

:request_id parameter is the id of request received in response of urls endpoint call




JSON response example:

{

   "request_id": 1,

   "request_status": "PENDING"

}

 

User needs endpoint

This is a GET endpoint

 

Endpoint path:

/api/brands/:brandId/user_needs/:request_id

:brandId parameter is the id of your brand

:request_id parameter is the id of request received in response of urls endpoint call

 

JSON response example:

{

   "request_id": 1,

   "request_status": "COMPLETED",

   "user_needs":  [

       {

           "success": true,

           "article_url": "www.test.com/article/123456",

           "user_needs": {

               "action_driven": true,

               "context_driven": true,

               "emotion_driven": false,

               "fact_driven": true

       },

       {

           "success": false,

           "article_url": "www.test.com/4567"

       }

   ]

}

In case of errors you would get error HTTP code and JSON payload

 

Example:

Request:

GET /api/brands/:brandId/user_needs/1

 

Response:

HTTP code 404

Payload:

{

   "message": "Request with id 1 not found"

}