Developer's API

FotoForensics provides the following guidelines for software developers who wish to interface with this site.
  1. API Restrictions
  2. Common API
  3. URL API
  4. File API
  5. API Results
  6. API for Accessing Data

  1. API Restrictions
  2. FotoForensics permits developers to create interfaces into FotoForensics as long as they abide by the following conditions:
    1. Cite the service. There must be a link to FotoForensics.com and/or attribution that cites FotoForensics.
    2. Free service. No fee is charged for accessing this data or for software that accesses this site.
    3. Ad-free service. No ads are used in conjunction with results from this site.
    4. No endorsements. It must be made clear that FotoForensics and Hacker Factor do not endorse your software or service.
    5. No automated uploads. Your service must not flood FotoForensics with requests. We are not Google; we do not have millions of load-balancing servers.
    6. API compliant. Your service abides by this site's API.
    The first condition relates to acknowledgements. Developers must not take credit for work performed by FotoForensics. Users must be made aware that data, content, or analysis is coming from FotoForensics.

    The next two conditions relate to Copyright Law. Images and text generated by FotoForensics can be used under Copyright's Fair Use clause. However, using the content to generate revenue -- directly, indirectly, or from ads -- violates Copyright and the Fair Use clause. In particular, many smartphone apps are ad-ware; they generate revenue by displaying third-party ads along with the app's content. If someone writes a smartphone app for FotoForensics, it must be a free app and must not be ad-based or sold for "$1 at the Apple Store". If you wish to create a profit-based front-end, you must contact Hacker Factor first. (Don't be surprised if Hacker Factor says "no" or requests a cut of the profits.)

    The next condition concerns endorsements and support. Basically, don't use the FotoForesics or Hacker Factor's name, web site, logo, or related content to give the impression of an endorsement. Abiding by this API is not an endorsement.

    The fifth condition concerns network and server loads. FotoForensics is intended as a research service and not a generic file-hosting site. While it usually can handle large floods (like those generated by Slashdot and Reddit), it is not intended for a single site or service to dominate the number of uploads. Automated uploads of dozens or hundreds of pictures is not permitted. We have specific filters that look for this type of abuse. We have currently blocked uploads from Google as well as other companies that attempted to upload hundreds of pictures. If you want to bulk upload pictures for analysis, contact Hacker Factor first.

    The final condition ensures that your application does not suddenly break when FotoForensics performs an update.

  3. Common API
  4. The common API is intended for other web sites, applications, and browser plugins to link to Fotoforensics. In particular, your service should redirect users to this site and not proxy partial content.

    FotoForensics does not support proxy services. In particular, FotoForensics does not permit pornography, nudity, or sexually explicit content. If your application redirects uploads to FotoForensics on behalf of users (e.g., you operate a proxy), then your service will be banned if any of your users submit prohibited content. (Trend Micro's content scanner has been banned for this reason; they uploaded porn on behalf of one of their users. Most Tor and open proxy nodes have also been banned for the same reason.) Whoever does the upload is responsible for ensuring that the content does not violate this policy.


    FotoForensics supports both GET and POST operations for uploading content. Content can either be specified as a URL or uploaded file.

  5. Uploading a URL
  6. To upload a URL to a picture to FotoForensics:
    • The request should be sent to "http://fotoforensics.com/upload-url.php".
    • The input must have a parameter named "url" with the value being the URL. Do not base64, html-encode, or otherwise alter the URL beyond the HTTP standard URI encoding. (If you use a standard HTTP library, then it should handle the encoding for you.) Do not send a "#" anchor with the URL; any "#" seen in the URL will be removed.
    • The HTTP "referer" header must either represent your service or where the user came from. Do not use a blank referer.
    • The HTTP "user-agent" must either represent your service or the user's user-agent. Do not use a blank user-agent. In particular, blank user-agent strings may be filtered due to abuse from spam-bots.
    • Standalone applications, such as browser plugins and smartphone apps, must identify themselves using the "plugin" and "pluginver" parameters. The "plugin" variable should be set to the name of your service or application. The "pluginver" should contain the version number. This way, problems with your service can be immediately reported to you, developer issues can be traced by grepping through logs, and future incompatibilities can be made backwards-compatible based on specific version numbers.
    A sample upload by URL may look like:
    GET /upload-url.php?plugin=SuperPlugin&pluginver=SuperPlugin-1.0&url=http://server/path/image.jpg HTTP/1.1
    Uploading by a URL may result in access problems. In particular, some pictures may only be accessible after the user logs into a secure system. (E.g., private Facebook photos and restricted forums.) If the FotoForensics server cannot access the image, then nothing will be downloaded. You should never send a user's login credentials to FotoForensics.

  7. Uploading a File
  8. To upload a file to FotoForensics:
    • The request should be sent to "http://fotoforensics.com/upload-file.php".
    • The input must have a parameter named "file" with the value being the file as a multipart form with UTF-8 encoding. The uploaded file must include the file's name.
    • The maximum file size is 5,242,880 bytes. This limit mitigates the risk from users attempting to dominate the file storage capacity, bandwidth, or file processing time. In particular, uploads that take longer than 15 seconds to process will be canceled. The time limit mitigates the risk from hostile uploads, browser connection timeouts, and massively large images that cannot be processed in real-time.
    • If possible, also supply a parameter named "FullPath" with the source path to the file. This is used for distinguishing evil bots from valid user requests. It is also used for debugging in case FotoForensics detects a problem with the upload. If the file upload came from a URL, then include the source URL. If the file upload came from the user's file system, then only include the filename.
    • Standalone applications, such as browser plugins and smartphone apps, must identify themselves using the "plugin" and "pluginver" parameters. The "plugin" variable should be set to the name of your service or application. The "pluginver" should contain the version number. This way, problems with your service can be immediately reported to you, developer issues can be traced by grepping through logs, and future incompatibilities can be made backwards-compatible based on specific version numbers.
    • Do not resave, resample, or convert the file before uploading. (For example, do not re-apply a JPEG compression or convert to PNG.) Re-encoding defeats the purpose of analyzing the file's last saved state. In addition, do not strip metadata since that can impact analysis. Just upload the user's file; don't crop, scale, recolor, or otherwise modify the user's contents.

      NOTE: Uploading a file via the Apple iOS HTTP system library will strip metadata and resave the file at a low quality. Do not use the Apple iOS HTTP system library for posting a file to a URL.
    From a networking viewpoint, the sample POST should look like:


    The filename in the final section may be just the name or an entire URL. A blank or static filename (e.g., using a hard-coded "foo.jpg" for every upload) is not permitted.

    A successful POST should return a "302" redirect code and the "Location" header identifies the URL to the picture.

  9. API Results
  10. After submitting the image to FotoForensics, it is strongly recommended that your service return the full response page to the user. Web browser plugins should open a new tab. Web pages should direct the user to FotoForensics. Using inline tags or HTML parsing is not recommended because this site may be redesigned in the future.

    The response will return an HTTP redirect (302 result code) to the results page. A redirect is used to prevent the browser's back button from performing a second upload. The HTTP redirect "Location" header points to the results page. The URL found in the Location header is the base URL for all of the results.

    A typical results page displays the analysis image. However, some response pages are text or have prompts for the user. Text pages are typically provided to banned users. The prompts are typically related to requests for the user to confirm that the image content does not violate the site's content restrictions.

    The type of response page is denoted in the HTML <title> field. The last word in the title identifies the result key.
    • If the title contains "Analysis", then the upload was successful.
    • The keyword "Verify" indicates that the content triggered one of the anti-porn filters and the user must confirm that the content is not prohibited. Do not automatically select the confirmation for the user since that will likely result in your application getting the user banned.
    • The keyword "Prohibited" means that the content has been blocked.
    • "Error" means that there was an upload problem.
    • If none of these keywords appear, then the upload failed either due to invalid content or a prohibited user.
    The API does not currently have a means to return different result codes. If there is a specific requirement for this, please contact Hacker Factor. Be sure to specify details concerning how you intend to use the results and interface with FotoForensics.

  11. API for Accessing Data
  12. After an image has been successfully uploaded, the analysis data can indexed using the image ID. The ID is the sha1 checksum of the uploaded picture and the length of the file. (Requiring both sha1 and length reduces the risk of a naming collision.) Pictures can be directly access using the following URL parameters:
    • id=sha1.length: Identifies the image
    • fmt=format: Identifies the return format. Current modes include 'orig' for the original image (png or jpeg), 'ela' for the error level analysis result (png), "estq" for the estimated last save JPEG quality (text), and "meta" for the extracted metadata (html for FotoForensic's CSS).
    • size=maxdimension: Scales the image to the maximum dimension. Arbitrary values are not permitted. The only supported values are 128, 256, 400, and 600. Scaled images will attempt to maintain the proper aspect ratio.
    For example, the following GET query will return the ELA image scaled to fit within a 600x600 pixel area:

    http://fotoforensics.com/analysis.php?id=a800d5aecce8c8a1eeea728833008bf14ee2afb2.10669&fmt=ela&size=600
If the picture failed to upload, then the analysis query will not return an image. If the id references prohibited/banned content, then a prohibited content image will be returned.

Last modified: 2016-11-09 19:46:33Z
Copyright 2012-2017 Hacker Factor, All Rights Reserved.System StatusBlogFAQContact