Recommendations Data Retrieval API

Threshr's "Recommendations" API allows users to retrieve a list of recommended NFTs based on utility information.
Users supply an ID and API Key as part of an https GET request.

⚠️

This API is under construction

Request

URL

https://threshr.co/api-gateway/recommendations (opens in a new tab)

Parameters

One parameter is required, nftId

Headers

One header is required to supply your API key:
Authorization: Bearer

Samples using Curl

Retrieve recommendations based on Starbucks' Coffee Heritage Journey Stamp (nftId = qz2evlt3faG8fgbcamTo)

curl https://threshr.co/api-gateway/recommendations?nftId=qz2evlt3faG8fgbcamTo -H "Authorization: Bearer <API Key>"

Performance Notes

⚠️

This API is under construction

As we begin our API expansion, the recommendations API does not run at full speed all the time. Making subsequent requests soon after an initial request will have much faster performance.

Response

Of most interest to users will be the matchedRef response parameter of the returned object. This corresponds to a recommended NFT.
Results are sorted based on similarity value.
ecoRef refers to all the ecosystems that an NFT belongs to, and NFTs in the same ecosystem are weighted higher.

Sample Response Body:

[
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "XFDzra69HC4ciFVeI8gU"
        },
        "similarity": 1.2,
        "ecoRef": [
            {
                "ID": "13"
            }
        ]
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "xV2HdnwFgtHK87Jq7EEX"
        },
        "similarity": 1,
        "ecoRef": [
            {
                "ID": "13"
            }
        ]
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "iv1pMRd02jHHzGxHOxus"
        },
        "similarity": 1,
        "ecoRef": [
            {
                "ID": "13"
            }
        ]
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "116"
        },
        "similarity": 0.1698512335372225,
        "ecoRef": []
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "111"
        },
        "similarity": 0.11499927611201063,
        "ecoRef": []
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "20"
        },
        "similarity": 0.07251818721835535,
        "ecoRef": []
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "127"
        },
        "similarity": 0.049206302798951454,
        "ecoRef": []
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "7I4WyRvWNMypKoFWqTUO"
        },
        "similarity": 0.04131046768552914,
        "ecoRef": []
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "126"
        },
        "similarity": 0.03975441877881577,
        "ecoRef": []
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "125"
        },
        "similarity": 0.03674957841078221,
        "ecoRef": []
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "104"
        },
        "similarity": 0.03323586166213989,
        "ecoRef": []
    },
    {
        "originalRef": {
            "ID": "qz2evlt3faG8fgbcamTo"
        },
        "matchedRef": {
            "ID": "jIcVCS1aF5zHePQOp2g4"
        },
        "similarity": 0.029690709527916057,
        "ecoRef": []
    }
]

Errors

Bad NFT Id

Using a bad NFT Id (try with "asdf") will return status code 400 Bad Request. The body of the response will be JSON:

    { "error": "Bad NFT Id" }

    { "error": "No recommendations, probably bad nft id." }

Too Many Requests

Surpassing the rate limit for the API will return status code 429 Too Many Requests. The body of the response will be JSON:

    {"error":"Too Many Requests"}

Ecosystem Search