Retrieving Similar Content

Object representing the verification of similar content to the one you uploaded to the database. You will need at least two content pieces to query similar content.

We offer tools to control the pool and prioritization of recommendations: whitelist and blacklist. Both operate at the source level and will soon be available.

  • Whitelist - Your source has a hierarchy. Views on some content pieces are more valuable than others. You can use the whitelist to drive more users to those pieces. If the content pieces added to the whitelist are eligible for recommendations, they appear in the first position. Being eligible means being part of the 30 relevant items (returned from this endpoint) suitable for recommendations. We don’t show irrelevant content to the final user. If two or more items added to the whitelist match given criteria, the first one in the whitelist comes first as a suggestion.

  • Blacklist - Your source contains a diverse set of content. For that reason, you might want to exclude some content from recommendations. When you blacklist a content, it doesn’t show as a recommendable item. It means that the recommendation list does not return the content.

Your access to such tools depends on your subscription plan.

Endpoint - GET /$source/content/$contentID/similar

This endpoint returns a list of a maximum of 30 content pieces similar to the one submitted in the query ($contentID). The content pieces rank by relevance, defined by the assigned score. The higher the score, the more relevant the content piece. You can request to display fewer content pieces in your frontend application.

Header Value Description
x-api-key Your API key String representing the value of the API key we sent you when you joined Rumo.


Example request:

curl -X GET \
  https://beta.api.rumo.co/{{$source}}/content/{{$contentID}}/similar \
  -H 'x-api-key: Your_Rumo_API_Key' \


Example request (with parameters):

curl -X GET \
    https://beta.api.rumo.co/{{$source}}/content/{{$contentID}}/similar?catalogs={{$catalogID}}&at={{$YYYY-MM-DD}}&take={{$take}} \
  -H 'x-api-key: Your_Rumo_API_Key' \


JSON response

{
    "id": "1",
    "content": [
        {
            "id": "3",
            "score": 0.7642977396044841
        },
        {
            "id": "2",
            "score": 1.0
        },
        {
            "id": "123",
            "score": 1.0
        }
    ]
}


Parameter Status Description
catalogs Optional String used to filter by catalog: ?catalogs=$catalogID
at Optional String used to filter by uploaded date: ?at=YYYY-MM-DD
take Optional Integer used to define the number of returned recommendations.


Returns Level Description
id 1 String used to identify a content piece.
content 1 String map with similar content IDs and corresponding scores.
id 2 String used to identify content pieces similar to the one recognized at level 1.
score 2 Integer identifying the relevance of the content piece.