Responses¶

All requests will be replied to with a JSON or XML string containing the documented variables for each method.

All JSON responses will contain a dictionary with keys while XML will contain elements under the root.

Key	Description
method	A string containing the name of the method that was called.
status	A string containing one of ok, warn, fail.
error	A list of error strings, describing any errors if status is set to warn or fail.
query_image	Information about the query image. This will appear for search calls.
result	A list of response numbers, strings or response dictionaries.
stats	A list of request stats contain timing info and some counters if applicable. All timing stats are in milliseconds.

result is a list of dictionaries containing multiple keys for a search call:

Key	Description
filepath	The collection image’s file path.
score	How closely the query image matches the collection image.
query_overlap_percent	How much the query image overlaps the collection image, as a percentage.
target_overlap_percent	How much the collection image overlaps the query image, as a percentage.
overlay	A URL pointing to the overlay for a search.

Example response to a search request¶

JSON¶

{
    "method": "search",
    "status": "ok",
    "error": [],
    "query_image": {
        "filepath": "query.jpg"
    },
    "result": [
        {
            "score": 100,
            "target_overlap_percent": 100,
            "match_percent": 100,
            "overlay": "overlay/?query=example2.jpg&target=example2.jpg&m21=-2.92719e-05&m22=0.999936&m23=0.012885&m11=0.999936&m13=0.014596&m12=2.92719e-05",
            "query_overlap_percent": 99.99,
            "filepath": "example2.jpg"
        },
        {
            "score": 20.20,
            "target_overlap_percent": 83.59,
            "match_percent": 29.22,
            "overlay": "overlay/?query=example2.jpg&target=example3.jpg&m21=0.0369254&m22=1.04451&m23=-11.8512&m11=1.04451&m13=-20.9172&m12=-0.0369254",
            "query_overlap_percent": 68.43,
            "filepath": "example3.jpg"
        }
    ],
    "stats": {
        "total_results": 2,
        "total_filtered_results": 2,
        "total_returned_results": 2,
        "time_resize": 43.8,
        "time_search": 178.51,
        "time_total": 223.23
    }
}

XML¶

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>search</method>
    <status>ok</status>
    <error/>
    <query_image>
        <filepath>query.jpg</filepath>
    </query_image>
    <result>
        <item>
            <filepath>example2.jpg</filepath>
            <match_percent>100.0</match_percent>
            <overlay>overlay/?query=example2.jpg&amp;target=example2.jpg&amp;m21=-2.92719e-05&amp;m22=0.999936&amp;m23=0.012885&amp;m11=0.999936&amp;m13=0.014596&amp;m12=2.92719e-05</overlay>
            <query_overlap_percent>99.99</query_overlap_percent>
            <score>100.0</score>
            <target_overlap_percent>100.0</target_overlap_percent>
        </item>
        <item>
            <filepath>example3.jpg</filepath>
            <match_percent>29.22</match_percent>
            <overlay>overlay/?query=example2.jpg&amp;target=example3.jpg&amp;m21=0.0369254&amp;m22=1.04451&amp;m23=-11.8512&amp;m11=1.04451&amp;m13=-20.9172&amp;m12=-0.0369254</overlay>
            <query_overlap_percent>68.43</query_overlap_percent>
            <score>20.20</score>
            <target_overlap_percent>83.59</target_overlap_percent>
        </item>
    </result>
    <stats>
        <total_results>2</total_results>
        <total_filtered_results>2</total_filtered_results>
        <total_returned_results>2</total_returned_results>
        <time_resize>43.8</time_resize>
        <time_search>178.51</time_search>
        <time_total>223.23</time_total>
    </stats>
</data>