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
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 SOAP service test page is: https://service.feng-gui.com/soap/api.asmx

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

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:

<?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":"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}]}

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.


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

<?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>

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

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

Original analyzed image
http://SERVICE/users/USERNAME/files/images/ImageID.png
Heatmap report
http://SERVICE/users/USERNAME/files/images/ImageID_heatmap.png
Gaze plot report
http://SERVICE/users/USERNAME/files/images/ImageID_gazeplot.png
Opacity report
http://SERVICE/users/USERNAME/files/images/ImageID_opacity.png
AOI report
http://SERVICE/users/USERNAME/files/images/ImageID_aoi.png
Aesthetics report
http://SERVICE/users/USERNAME/files/images/ImageID_aes.png
Analysis information
http://SERVICE/users/USERNAME/files/images/ImageID_info.txt
Raw data report
http://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 original image URL
USERNAME: Your Feng-GUI account name.

Arguments

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

ViewType (integer)
   View Type sets 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)
   View Distance sets 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 Desktop Screen
Desktop Screen	1	laptop or 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 Billboard	6	Billboards, Outdoor Advertising 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 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 raw attention file.
Hotspots - Array of Hotspots points (named FGPoint)
   FGPoint holds a point location (x,y) within the return image.

example 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>
    <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>

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.png
   https://service.feng-gui.com/users/USERNAME/files/images/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/images/9aa34142-669d-4261-a08f-f80b4c0b58ba_heatmap.png
The ImageID is 9aa34142-669d-4261-a08f-f80b4c0b58ba

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 = '[{"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/images/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

<?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>

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/images/9aa34142-669d-4261-a08f-f80b4c0b58ba.png

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>string</GetImageAOIsResult>
    </GetImageAOIsResponse>
  </soap:Body>
</soap:Envelope>

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.


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

Arguments

none

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>

Credit: one credit is charged for a successful execution.

Upload an image file to your account.

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.



Credit: one credit is charged for a successful execution.

Capture a Website as an image and upload the image file to your account.

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.



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