Feng-GUI Web Services: API Documentation

Feng-GUI has an open web Application Programming Interface.
This means that you can integrate your own program with Feng-GUI services.
Feng-GUI API partners vary from digital marketing agencies through e-mail-marketing vendors to packaging design vendors.

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.com to add the 'api' role to your account
4. After you have learned how to use API, build your own application.


Roles

A Role indicates the levels of permissions a user have while operating a method.
Your account is associated with one or more Roles.
Account Roles depends on package plans and the Feng-GUI partnership level you have.
To use the API, your account must include the 'api' role.
Please contact sales@feng-gui.com and request to add the 'api' role to your account.
Your account roles may be found at Settings > Account Details > Roles


Authentication

Feng-GUI services required HTTP Basic authentication for all methods.
HTTPS/TLS should be used in conjunction with HTTP Basic authentication.


Storage

API partners should download the report files from Feng-GUI service onto their servers.
The report files are deleted within 24 hours.


API Format

To perform an action using the API, you need to invoke a SOAP or JSON-RPC request to its endpoint specifying a method and some arguments, and will receive a formatted response.


SOAP format

The SOAP service Endpoint URL is: https://service.feng-gui.com/soap/api.asmx
SOAP service description (WSDL) is at https://service.feng-gui.com/soap/api.asmx?wsdl
SOAP service test page is: https://service.feng-gui.com/soap/api.asmx
Note: Your service domain could be different than "service.feng-gui.com".
Your account service domain information may be found at Settings > Account Details > Service.

SOAP Request

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, '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

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:
<?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 https://www.jsonrpc.org/specification_v1

The JSON service Endpoint URL is: https://service.feng-gui.com/json/api.ashx
Help page is: https://service.feng-gui.com/json/api.ashx?help
Test page is: https://service.feng-gui.com/json/api.ashx?test

Note: Your service domain could be different than "service.feng-gui.com".
Your account service domain information may be found at Settings > Account Details > Service.


JSON Request

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

A request call to the method returns the response:
{"serviceVersion":"6.0.0.0","version":"6.0.0.0",
"inputImage":"https://service.feng-gui.com/users/customer/files/images/IMAGEID.png", "outputImage":"https://service.feng-gui.com/users/customer/files/images/IMAGEID_heatmap.png",
"outputAttentionImage":"https://service.feng-gui.com/users/customer/files/images/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
If an error occurs, the following response example is returned:
{"name":"JSONRPCError","message":"error description.","errors":[{"name":"JsonRpcException","message":"error description."}]}


Additional JSON syntax

HTTP GET
The JSON-RPC service expects to receive an HTTP POST request. The service also support HTTP GET using the syntax:
https://service.feng-gui.com/json/api.ashx/METOD?PARAM1=VALUE1&PARAM2&VALUE2
for example https://service.feng-gui.com/json/api.ashx/echo?InputString=testString

Javascript

You can use javascript to make JSON-RPC calls to Feng-GUI API.

<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Feng-GUI JSON-RPC Javascript example</title>
<script type="text/javascript" src="https://service.feng-gui.com/json/json.js?v=7.4.3"></script>
<script type="text/javascript" src="https://service.feng-gui.com/json/apiProxy.js?v=7.4.3"></script>

<script type="text/javascript">
window.onload = function()
{
  var service1 = new api('https://service.feng-gui.com/json/api.ashx', 'username', 'password');

  // echo method
  service1.echo("test string",function(response) {
    document.getElementById('log').innerHTML += '<br>echo:' + response.result;
  });

	
  // GetAccountInfo method
  service1.GetAccountInfo("username",function(response) {
    var AccountInfo = response.result;
    document.getElementById('log').innerHTML += '<br>GetAccountInfo.credit:' + AccountInfo.credit;
    document.getElementById('log').innerHTML += '<br>GetAccountInfo.used:' + AccountInfo.used;
  });

}
</script>

</head>
<body>

  <div id="log">output:</div>

</body>


echo method

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

Arguments

value (string)
   input string to echo

Response

  The response is a string with the value of the input string to echo.

ImageAttention method

Feng-GUI attention analysis of an image.
Credit: one credit is charged for an image analysis.
Method applies to image analysis.

The method generates the Attention, Gaze, Opacity, AOIs and Aesthetics reports in one execution.

Input image to analyze
https://SERVICE/users/USERNAME/files/images/ImageID.png
Heatmap image report
https://SERVICE/users/USERNAME/files/images/ImageID_heatmap.png
Gaze plot image report
https://SERVICE/users/USERNAME/files/images/ImageID_gazeplot.png
Opacity image report
https://SERVICE/users/USERNAME/files/images/ImageID_opacity.png
AOI image report
https://SERVICE/users/USERNAME/files/images/ImageID_aoi.png
Aesthetics image report
https://SERVICE/users/USERNAME/files/images/ImageID_aes.png
Analysis information
https://SERVICE/users/USERNAME/files/images/ImageID_info.txt
Raw data image report
https://SERVICE/users/USERNAME/files/images/ImageID_raw.png

SERVICE: Service endpoint domain name. for example service.feng-gui.com
ImageID: The relative file name of the input image or video URL including the file extension .png or .mp4
USERNAME: Your Feng-GUI account name.

Arguments

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

ViewType (integer)
   Visual View Type sets the content kind of the image or video. 
   This parameter is a value from one of the following flags.
 
Name Value Description
Any 0 Default
Website 1 internet web page
Natural 2 Photo, Advertisement, Video
Package 3 Package, Shelf
Indoor Signage 4 Indoor Signs, Signage
Outdoor Signage 5 Billboards, Outdoor Advertising and Large Format Printing

viewDistance (integer)
   View Distance sets the viewer's distance from the image or video. 
   This parameter is a value from the following group of flags.

Name Value Description
Any 0 Default
Computer Screen 1 Laptop or Desktop computer screen.
Mobile 2 Mobile or Handheld device
Print 3 Printed media, Magazine and Newspaper
Indoor Signage 4 Indoor Signs, Signage
Package Design 5 Packaging design
Outdoor Signage 6 Outdoor Advertising, Billboards and Large Format Printing

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.
AnalyzeFlicker 16 Include Flicker analysis.
This value is effective only when analyzing a series of frames in a video.
AnalyzeMotion 32 Include Motion analysis.
This value is effective 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

Remarks
Since we have the GazePlot report, the yellow gaze path in the heatmap report is obsolete and no longer valuable.
You can remove the yellow gaze plot from the heatmap report by disabling the DrawHotSpots, DrawGaze and DrawGazeOrder outputOptions parameters.

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.
OutputOpacityWhite 32 Create Opacity report with white overlay instead of default black overlay.
OutputAutoAddAOIs 64 Auto create and add AOIs to the AOIs list.

Response

The response is 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 raw attention file.
Hotspots - Array of Hotspots points. (named FGPoint)
   FGPoint holds a point location (x,y) within the return image.
AOIs - Array of AOIs. (named ImageAnnotation)
   ImageAnnotation holds a rectangle position and its fixation data.


SetImageAOIs method

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

Arguments

ImageID (String): The relative file name of the original image or video URL including the file extension .png or .mp4
   for example, the image id of the following URL is /folder/uuid.png
   https://service.feng-gui.com/users/USERNAME/files/images/folder/uuid.png
AOIs (String)
   JSON format string of the AOIs regions.

Example

To generate an AOIs report:
1. Call ImageAttention method with the URL of the image located on your server.
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/images/uuid_heatmap.png
The ImageID is uuid.png

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

AOIs = '[{"units":"pixels","top":36,"left":75,"width":40,"height":40,"text":"face","id":"uuid1"},
{"units":"pixels","top":3,"left":220,"width":40,"height":50,"text":"product","id":"uuid2"},
{"units":"pixels","top":82,"left":14,"width":40,"height":40,"text":"face2","id":"uuid3"},
{"units":"pixels","top":0,"left":3,"width":32,"height":20,"text":"company name","id":"uuid4"},
{"units":"pixels","top":212,"left":317,"width":55,"height":23,"text":"brand name","id":"uuid5"},
{"units":"pixels","top":192,"left":221,"width":136,"height":25,"text":"tag line","id":"uuid6"}]'

4. Call ImageAttention method with the URL of the image located on Feng-GUI server. No credit is charged when analyzing images located on Feng-GUI server.
5. 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/images/uuid_aoi.png + "?" + (new Date()).getTime();
The report files are http cached and if you will not add a random parameter (like timestamp) to the URL, you might receive an HTTP status "304 Not Modified"

Response

None



GetImageAOIs method

Get the AOIs data of an image.
Credit: no credit is charged when using this method.
Method applies to image analysis.

Arguments

ImageID (String): The relative file name of the original image or video URL including the file extension .png or .mp4
   for example, the image id of the following URL is /folder/uuid.png
   https://service.feng-gui.com/users/USERNAME/files/images/folder/uuid.png

Response

The response is a string with the AOIs data in JSON format.

Example SOAP Response
<?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>[{"id":"8809ba3e-0ef5-147a-573d-906bbc26fa14","text":"aoi1","units":"pixels","top":72.0,"left":145.0,"width":36.0,"height":36.0,"VisibilityScore":25,"TimeToFirstFixation":0,"FixationsBefore":0,"FixationLength":0,"FixationCount":0,"intensity":0,"orientation":0,"colorRedGreen":0,"colorBlueYellow":0}]
</GetImageAOIsResult>
    </GetImageAOIsResponse>
  </soap:Body>
</soap:Envelope>

Scaled AOI values
AOI values can be scaled to several units: 'pixels', 'percent', '384x256'
3/2020 Update: Scaling AOI units to '384x256' is not mandatory anymore. You can specify the exact pixels position, by set the units as 'pixels'
9/2020 Update: GetImageAOIs is not scaling AOIs into '384x256'. The units of the returned AOIs are the same as saved.

Here is how to calculate '384x256' scaled AOI values for a 1024x768 pixels 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 of an AOI of units:'384x256',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

[{"units":"384x256","top":33,"left":33,"width":17,"height":17,"text":"face","id":"uuid1"}]


ImageUpload method

Upload an image file to your account.
The file is uploaded into the root of the account folders.
Credit: one credit is charged for a successful execution.
Method applies to image analysis.

Tip: Instead of using ImageUpload method, you can upload the input image to your server and set the ImageAttention.InputImage parameter as the URL path of the image.

Arguments

   FileName - The name of the uploaded file. Notice that uploaded file is renamed by the service into a new random unique name.
   FileData - The uploaded file encoded as base64 byte array.

Response

   The response is a string with the new file name of the uploaded file.


WebsiteCapture method

Capture a Website as an image and upload the image file to your account.
The file is uploaded into the root of the account folders.
Credit: one credit is charged for a successful execution.

Tip: Instead of using ImageUpload method, you can upload the input image to your server and set the ImageAttention.InputImage parameter as the URL path of the image.



VideoAttention method

Feng-GUI attention analysis of a video.
Credit: one credit is charged for every 10 seconds of video.
Method applies to video analysis.

The method generates the Attention heatmap video

Input video to analyze
http://SERVICE/users/USERNAME/files/images/ImageID.mp4
Heatmap video report
http://SERVICE/users/USERNAME/files/images/ImageID_heatmap.mp4
Gaze Data fixations tsv file
http://SERVICE/users/USERNAME/files/images/ImageID_gazedata.tsv


VideoUpload method

Upload a video file to your account.
The file is uploaded into the root of the account folders.
Credit: one credit is charged for every 10 seconds of video.
Method applies to video analysis only.

Arguments

   FileName - The name of the uploaded file. Notice that uploaded file is renamed by the service into a new random unique name.
   FileData - The uploaded file encoded as base64 byte array.

Response

   The response is a string with the new file name of the uploaded file.
Tip: Instead of using VideoUpload method, you can upload the input video to your server and set the VideoAttention.InputVideo parameter as the URL path of the video.


CreateReport method

Create a pdf report.
Credit: no credit is charged when using this method.
Method applies to image analysis only.

Arguments

ImageID (String): The relative file name of the image or video including file extension .png or .mp4
   ReportTemplate - Report template file name. default:'template.mdddl'
   parameters - extra query string parameters sent to the report. for internal use. default:''

Response

   The response is a string with the URL of the report pdf file.



GetAccountInfo method

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

Arguments

AccountID - The user name in Feng-GUI system.

Response

The response is 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, api, readonly, annual.
Status   String. account status. enabled disabled.
Used   String. How many credits used.
Credit   String. How many valid credits.
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.

Example JSON response
{"id":1,"result":{"userName":"test","password":"password","email":"test@feng-gui.com",
"roles":"customer,annual,api,readonly","status":1,
"used":902,"credit":698,"service":"https://service.feng-gui.com",
"dateAdd":"2010-03-13 16:15:34","firstName":"test","lastName":"surename",
"address":"","city":"","zipCode":"","country":"","company":"","storage":0,"mailing":0}}



GetAccountUsage method

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

Arguments

None.

Response

The response is an array of rows. Example SOAP response
<?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>

Example JSON response
{"id":2,
"result":{"rows":[{"id":"245804","type":"2","value":"https://service.feng-gui.com/users/test1/files/images/3625b0882eac.png analyzed as 3625b0882eac.png","dateAdd":"2020-01-15 16:59:10"},
{"id":"245803","type":"5","value":"3625b0882eac.png template.mdddl","dateAdd":"2020-01-15 15:51:13"},
{"id":"245802","type":"2","value":"https://service.feng-gui.com/users/test/files/images/3625b0882eac.png analyzed as 3625b0882eac.png","dateAdd":"2020-01-15 15:50:49"},
{"id":"245801","type":"1","value":"Screen Shot 2020-01-15 at 2.45.49 PM.png saved as af564223-d56b-4ea2-8e6f-3625b0882eac.png","dateAdd":"2020-01-15 15:49:12"},
]}}



GetServiceStatus method

Check the status of the service.
Credit: no credit is charged when using this method.
Method applies to image and video analysis.

Use this method to check if a file is currently being analyzed.
Video analysis is done asynchronously and take at least a few minutes. Use this method to realize if the video analysis is still running.

Arguments

ImageID (String): The relative file name of the original image or video URL including the file extension .png or .mp4

Response

The response is an Integer: 0 idle, 1 busy.




Exceptions and Error Codes

An exception that signals that a SOAP or JSON 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 failure cause.

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 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 and the service return HTTP error "503 Service Temporarily Unavailable" error.

FilesOperationException
   File and directory operation errors.
   See the exception message for more details about the failure cause.

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 web page or image failed
   The request has failed to retrieve the image file or the webpage.