Feng-GUI Web Services: API Documentation

Feng-GUI has an open web Application Programming Interface.
This means that you can write your own program to integrate Feng-GUI technologies and services in new and different ways.
For example, you could automate web usability testing, develop a mobile App or create a Photoshop plugin

Developing on the Feng-GUI API

Anyone can write software to do cool stuff with available Feng-GUI technology via our API.
Here's how to get started:
1. Review and agree to the API license agreement.
2. Read the API documentation below. Feel free to send us some feedback.
3. Request for an evaluation API account. email to: sales@feng-gui
4. Your account must have the 'api' role.
5. After you have learned how to use API and you have your authentication credentials, build your own application.

API Format

To perform an action using the API, you need to invoke a SOAP or JSON request to its endpoint specifying a method and some arguments, and will receive a formatted response.
The SOAP service Endpoint URL is: https://service.feng-gui.com/soap/api.asmx
The SOAP service description (WSDL) is at https://service.feng-gui.com/soap/api.asmx?WSDL
The JSON service Endpoint URL is: https://service.feng-gui.com/json/api.ashx
The JSON service test page is: https://service.feng-gui.com/json/api.ashx?test
Your service domain could be different than "service.feng-gui.com".
Your account service domain information may be found at Dashboard > Account Details > Service.

SOAP Request Format

The following is a sample SOAP 1.2 request. The placeholders shown need to be replaced with actual values.
To send a request (for example, to echo method), send a request like this:
POST /soap/api.asmx HTTP/1.1
Host: service.feng-gui.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://www.feng-gui.com/echo"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <echo xmlns="http://www.feng-gui.com/">
      <value>string</value>
    </echo>
  </soap:Body>
</soap:Envelope>

SOAP Response Format

The following is a sample SOAP 1.2 response. The placeholders shown need to be replaced with actual values.
A request call to the echo method returns this response:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <echoResponse xmlns="http://www.feng-gui.com/">
      <echoResult>string</echoResult>
    </echoResponse>
  </soap:Body>
</soap:Envelope>

JSON Format

The JSON API is based on the JSON-RPC version 1.0 specification
For more information about JSON-RPC, visit http://json-rpc.org/wiki/specification

The JSON Server Endpoint URL is: https://service.feng-gui.com/json/api.ashx

You can try all the API methods via a web browser, at https://service.feng-gui.com/json/api.ashx?test

JSON Request Format

To send a request , for example, to ImageAttention, send a request like this:
{ "InputImage" : 
"https://service.feng-gui.com/users/customer/files/images/IMAGEID.png",
"ViewType" : 0, "ViewDistance" : 0, "analysisOptions" : 0, "outputOptions" : 0}

JSON Response Format

A request call to the method returns the response:
{"serviceVersion":"5.0.0.0","version":"5.0.0.0",
"inputImage":"https://service.feng-gui.com/users/customer/files/images/IMAGEID.png", "outputImage":"https://service.feng-gui.com/users/customer/files/heatmaps/IMAGEID.png",
"outputAttentionImage":"https://service.feng-gui.com/users/customer/files/heatmaps/IMAGEID_raw.png",
"hotspots":[{"x":378,"y":168},{"x":251,"y":184},{"x":562,"y":385},
{"x":60,"y":373},{"x":330,"y":182},{"x":483,"y":366},{"x":392,"y":120},
{"x":109,"y":171},{"x":105,"y":395},{"x":-1,"y":-1}]}

Error Response Format
If an error occurs, the following response example is returned:
{"name":"JSONRPCError","message":"error description.","errors":[{"name":"JsonRpcException","message":"error description."}]}


Authentication

Feng-GUI services required HTTP Basic authentication for all methods.

Roles

A Role indicates the levels of permissions a User have while operating a method.
Your account is associated with one or more Roles, and it is most likely that your Roles depends on the Feng-GUI partnership level you have.
To use all of the API functionality, your account should include the "api" role.
Please contact sales@feng-gui and request to add the "api" role to your account.
Your account roles may be found at Dashboard > Account Details > Roles


echo method

A testing method which echo's all parameters back in the response.
Credit: no credit is charged when using this method.

Arguments

value - input string to echo

Request

POST /soap/api.asmx HTTP/1.1
Host: localhost
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://www.feng-gui.com/echo"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <echo xmlns="http://www.feng-gui.com/">
      <value>string</value>
    </echo>
  </soap:Body>
</soap:Envelope>            

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <echoResponse xmlns="http://www.feng-gui.com/">
      <echoResult>string</echoResult>
    </echoResponse>
  </soap:Body>
</soap:Envelope>


ImageAttention method

Feng-GUI attention analysis of an image.
Credit: one credit is charged for a successful execution.

The ImageAttention method generates the Attention, Gaze, Opacity and AOIs reports in one execution and in a single credit cost.

Original analyzed image
http://SERVICE/users/USERNAME/files/heatmaps/ImageID.png
Gaze plot report
http://SERVICE/users/USERNAME/files/heatmaps/ImageID_gazeplot.png
Opacity report
http://SERVICE/users/USERNAME/files/heatmaps/ImageID_opacity.png
AOI report
http://SERVICE/users/USERNAME/files/heatmaps/ImageID_aoi.png
Analysis information
http://SERVICE/users/USERNAME/files/heatmaps/ImageID_info.txt

ImageID: The file name of the returned OutputImage URL
USERNAME: Your Feng-GUI account name.
SERVICE: Service endpoint domain name. for example service.feng-gui.com

Arguments

InputImage (string)
   Full URL (http://...) path of the input image file.

ViewType (integer)
   The content kind of the image. 
   This parameter is a value from one of the following flags.
 
Name Value Description
Default 0
Photo 1 Natural image
Website 2 internet web page
Billboard 3 road billboard
Advertisement 4 print or digital advertisement photo

viewDistance (integer)
   The viewer's distance from the image. 
   This parameter is a value from the following group of flags.

Name Value Description
Default 0 Default is centimeters
Centimeters 1 computer, newspaper.
Meters 2 A distance image. for example billboard

analysisOptions (integer)
Specifies the sub algorithms used in the analysis. This parameter is a combination of accumulated flags from the following group of flags.
For example, to include Visual Features (63) and AnalyzeFace (128), set the analysisOptions = 63 + 128 = 191

Name Value Description
Default 0 Basic Visual Features analysis.
Extended Visual Features 15 Include Extended Visual Features analysis. Extended Visual Features, are a collection of bottom-up and top-down cognitive features which are not available at the free version of Feng-GUI
AnalyzeFlicker 16 Include Flicker analysis.
Include this value, only when analyzing a series of frames in a video.
AnalyzeMotion 32 Include Motion analysis.
Include this value, only when analyzing a series of frames in a video.
AnalyzeText 64 Add text detection to the analysis
AnalyzeFace 128 Add face detection to the analysis
AnalyzeSkin 256 Add Skin Hue detection to the analysis

outputOptions
Specifies how the output heatmap file is generated and its content. This parameter is a combination of accumulated flags from the following group of flags.
For example, to include MergeHeatmap (1) and DrawHotSpots (2), set the outputOptions = 1 + 2 = 3

Name Value Description
Default 0 Default output settings
MergeHeatmap 1 Should the output contain a merged layer of the input image
DrawHotSpots 2 Should the heatmap include hotspot circles.
DrawGaze 4 Should the heatmap include gaze lines between hotspot.
DrawLegend 8 Should the heatmap include a map legend watermark.
DrawGazeOrder 16 Should the heatmap include the gaze order number.

Response

The ImageAttention method returns a HeatmapInfo struct.
HeatmapInfo struct properties
ServiceVersion - Service version.
Version - Attention analysis version.
InputImage - URL location of the input image file.
OutputImage - URL location of the output file.
   The OutputImage file is not persisted and might be deleted, within an hour. You have to download the OutputImage file and save it for further use.
OutputAttentionImage - Internal URL location of the grayscale attention file. This property is for internal use only and is not supported.
Hotspots - Array of Hotspots points (named FGPoint)
   FGPoint holds a point location (x,y) within the return image.

example response
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ImageAttentionResponse xmlns="http://www.feng-gui.com/">
      <ImageAttentionResult>
        <ServiceVersion>string</ServiceVersion>
        <Version>string</Version>
        <InputImage>string</InputImage>
        <OutputImage>string</OutputImage>
        <OutputAttentionImage>string</OutputAttentionImage>
        <Hotspots>
          <FGPoint>
            <x>int</x>
            <y>int</y>
          </FGPoint>
          <FGPoint>
            <x>int</x>
            <y>int</y>
          </FGPoint>
        </Hotspots>
      </ImageAttentionResult>
    </ImageAttentionResponse>
  </soap:Body>
</soap:Envelope>


SetImageAOIs method

Set the AOIs data of an image.
Credit: no credit is charged when using this method.

Arguments

ImageID (String)
   The unique id of an image.
   for example, the image id of the following URL is 9aa34142-669d-4261-a08f-f80b4c0b58ba
   https://service.feng-gui.com/users/USERNAME/files/heatmaps/9aa34142-669d-4261-a08f-f80b4c0b58ba.png
AOIs (String)
   JSON format string of the AOIs regions.

Scale AOI values
AOI values need to be scaled to 384x256

Here is how to calculate the AOI values for a 1024x768 image:
aoiWidth = 384
aoiHeight = 256
imgWidth = 1024
imgHeight = 768

aoiRatio = aoiWidth / aoiHeight
imageRatio = imgWidth / imgHeight

if (aoiRatio < imageRatio) {
  aoiHeight = aoiWidth / imageRatio
}
else {
  aoiWidth = aoiHeight * imageRatio
}

aoi.top = realAoi.top / (imgHeight / aoiHeight)
aoi.left = realAoi.left / (imgWidth / aoiWidth)
aoi.width = realAoi.width / (imgWidth / aoiWidth)
aoi.height = realAoi.height / (imgHeight / aoiHeight)
calculation example for an AOI of top:100,left:100,width:50,height:50
aoiRatio = 384 / 256 = 1.5
imageRatio = 1024 / 768 = 1.3333
aoiHeight = 256
aoiWidth = 256 * 1.3333 = 341.333
aoi.top = 100 / (768 / 256) = 33.33
aoi.left = 100 / (1024 / 341.333) = 33.33
aoi.width = 50 / (1024 / 341.333) = 16.66
aoi.height = 50 / (768/ 256) = 16.66

[{"top":33,"left":33,"width":17,"height":17,"text":"face","id":"1","editable":true}]

Example

To generate an AOIs report:
1. Call ImageAttention method.
2. From ImageAttention response, extract the newly created ImageID from the OutputImage URL
Here is an example of OutputImage URL
https://service.feng-gui.com/users/USERNAME/files/heatmaps/9aa34142-669d-4261-a08f-f80b4c0b58ba.png
The ImageID is 9aa34142-669d-4261-a08f-f80b4c0b58ba

3. Use this ImageID and a JSON AOIs string to call SetImageAOIs(ImageID, AOIs)
Here is an example of an AOIs string

[{"top":36,"left":75,"width":40,"height":40,"text":"face","id":"1","editable":true},
{"top":3,"left":220,"width":40,"height":50,"text":"product","id":"2","editable":true},
{"top":82,"left":14,"width":40,"height":40,"text":"face2","id":"3","editable":true},
{"top":0,"left":3,"width":32,"height":20,"text":"company name","id":"4","editable":true},
{"top":212,"left":317,"width":55,"height":23,"text":"brand name","id":"5","editable":true},
{"top":192,"left":221,"width":136,"height":25,"text":"tag line","id":"6","editable":true}]

4. Download the AOIs report image with an additional timestamp parameter at the end of the URL. For example:
https://service.feng-gui.com/users/USERNAME/files/heatmaps/9aa34142-669d-4261-a08f-f80b4c0b58ba_aoi.png + "?" + (new Date()).getTime();
The AOIs report files are http cached and if you will not add a random parameter (like timestamp) to the URL, you will receive an HTTP status "304 Not Modified"

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SetImageAOIsResponse xmlns="http://www.feng-gui.com/" />
  </soap:Body>
</soap:Envelope>


GetImageAOIs method

Get the AOIs data of an image.
Credit: no credit is charged when using this method.
The response AOIs data is in JSON format.

Arguments

ImageID - The unique id of an image.
   for example, the image id of the following URL is 9aa34142-669d-4261-a08f-f80b4c0b58ba
   https://service.feng-gui.com/users/USERNAME/files/heatmaps/9aa34142-669d-4261-a08f-f80b4c0b58ba.png

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetImageAOIsResponse xmlns="http://www.feng-gui.com/">
      <GetImageAOIsResult>string</GetImageAOIsResult>
    </GetImageAOIsResponse>
  </soap:Body>
</soap:Envelope>


GetAccountInfo method

Get profile properties, credit and usage information of your account id.
Credit: no credit is charged when using this method.

Arguments

AccountID - The user name in Feng-GUI system.

Response

The GetAccountInfo method returns an AccountInfo struct.
AccountInfo struct
UserName   String. The account user name.
Password   String. password.
Email   String. The account email or comma separated emails list.
Roles   String. guest, customer, evaluation, test.
Status   String. account status. enabled disabled.
Used   String. how much credit was used.
Credit   String. non expired valid credit.
Service   String. service end point host address.
DateAdd   String. date account was created.
FirstName   String.
LastName   String.
Address   String.
City   String.
ZipCode   String.
Country   String.
Company   String.
Storage   Integer.
Mailing   Integer.


GetAccountUsage method

Get account usage for the recent 100 actions.
Credit: no credit is charged when using this method.

Arguments

none

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetAccountUsageResponse xmlns="http://www.feng-gui.com/">
      <GetAccountUsageResult>
        <Rows>
          <GenericRow>
            <Id>string</Id>
            <Type>string</Type>
            <Value>string</Value>
            <DateAdd>string</DateAdd>
          </GenericRow>
          <GenericRow>
            <Id>string</Id>
            <Type>string</Type>
            <Value>string</Value>
            <DateAdd>string</DateAdd>
          </GenericRow>
        </Rows>
      </GetAccountUsageResult>
    </GetAccountUsageResponse>
  </soap:Body>
</soap:Envelope>


ImageUpload method

This method is for internal use only and is not supported.
Feng-GUI reserves the right to change this method at any time.
Credit: one credit is charged for a successful execution.

To analyze images, use the ImageAttention method.
Upload the image to Your server and set the InputImage parameter as the URL path of the image.

Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ImageUploadResponse xmlns="http://www.feng-gui.com/">
      <ImageUploadResult>string</ImageUploadResult>
    </ImageUploadResponse>
  </soap:Body>
</soap:Envelope>


Exceptions and Error Codes

An exception that signals that a SOAP or XML/RPC exception has occurred.
Credit: Credit is not charged for an unsuccessful transaction.

Exceptions


CaptureFailedException
   Analysis creation failed. See the exception message for more details about the root cause of the failure.

ServiceTimeoutException
   The operation has reached timeout.
   It is most likely that you are using a very large image. Try to reduce the image dimensions and invoke the method again.

InsufficientRolePermissionsException
   Your account role has insufficient permissions to perform this operation.

InsufficientCreditException
   There is not enough credit in your account to perform this operation.
   When you ran out of credits, you cannot upload or analyze new images.
   When credits package expires, you cannot analyze an existing image.

ConsecutiveLoginFailuresException
   To prevent hackers from brute force login, an account will be disabled for 10 minutes after 3 consecutive login failures.
   The API Throws the ConsecutiveLoginFailuresException exception aling with an HTTP "503 Service Temporarily Unavailable" error.

Error Codes


96: Login failed
   The login details passed were invalid.

97: User not logged in
  The method requires user authentication but the user was not logged in.

98 Insufficient Role permissions
   The authenticated user did not have the required Role permissions.

105: Service currently unavailable
   The requested service is temporarily unavailable.

112: Method "method name" not found
   The requested method was not found.

115: Invalid XML-RPC Method Call
   The XML-RPC request document could not be parsed.

116: Capture website or image failed
   The request has failed to retrieve the image file or the webpage.