Recommendations

JSON (GET)

Endpoint

GET https://api.mediego.com/1.0/recommendations/json

Parameters

Configuration of the recommender system

The following parameters are provided by Mediego. They identify the configuration of the client and how the recommendations should be computed and returned.

Name Description
engine Client ID
source Configuration ID
campaign (optional) Used for newsletters only. It allows to group multiple recommendation requests in the same campaign.
format (optional) JSON format that should be returned
debug (optional) Specify if the request is only for debug and thus should not be recorded

Identification of the user

One of the following parameter is necessary to idenfity the user.

Name Description
euid Client user ID
muid Mediego user ID

Identification of the item

One of the following parameter is necessary to idenfity the item that the user is currently visiting. An item can be a web page an article or product.

Name Description
referrer URL of the visited page
eiid Client item ID
miid Mediego item ID

Response

By default the response of a recommendation request is as following.

Success

{
    {
        "headers": {
            "muid": string, // Mediego user ID
            "engine": number, // Client ID
            "target": string, // Target property for links (<a>)
            "display_id": string, // ID of the display (recommendation request)
        },
        "items": [
         {
            "id": string, // ID of the recommendation
            "title": string,
            "description": string,
            "image": string,
            "link": string, // Link to the recommended item (tracking parameters are included)
            "metadata": object, // Object containing metadata of the item
            "categories": string[], // Categories of the recommended item
            "date": number // Timestamp of the recommendation
         },
         ...
        ]
    }
    
    
}

If the default format does not suit your needs, we can develop a specific one. In this case, the format parameter allows you to change the returned format.

Error

{
    "error": string // Description of the error    
}

JSON (POST)

Endpoint

POST https://api.mediego.com/1.0/recommendations/json

Parameters

The parameters are the same as the GET version. However, they are sent as a JSON object in the body of the request.

{
  "engine": string,
  "source": string,
  "campaign": string,
  "format": string,
  "debug": boolean,
  
  "euid": string,
  "muid": string,
  
  "referrer": string,
  "eiid": string,
  "miid": string,
  
  "blacklistedItems": string[]
}

In addition, the POST request allows to define a list of blacklisted items. This can be useful if you already displayed some items to a user and don't want them to appear in our recommendations.

Name Description
blacklistedItems Items (in the form of a list of Client item IDs) that must not appear in recommendations

Response

By default the response of a recommendation request is as following.

Success

{
    {
        "headers": {
            "muid": string, // Mediego user ID
            "engine": number, // Client ID
            "target": string, // Target property for links (<a>)
            "display_id": string, // ID of the display (recommendation request)
        },
        "items": [
         {
            "id": string, // ID of the recommendation
            "title": string,
            "description": string,
            "image": string,
            "link": string, // Link to the recommended item (tracking parameters are included)
            "metadata": object, // Object containing metadata of the item
            "categories": string[], // Categories of the recommended item
            "date": number // Timestamp of the recommendation
         },
         ...
        ]
    }
    
    
}

If the default format does not suit your needs, we can develop a specific one. In this case, the format parameter allows you to change the returned format.

Error

{
    "error": string // Description of the error    
}

HTML

Endpoint

GET https://api.mediego.com/1.0/recommendations/html

Parameters

The parameters are the same as the request for recommendations in JSON.

Response

Success

HTML code representing the template filled with computed recommendations

<html>
 // Your template here
</html>

Error

{
    "error": string // Description of the error    
}

JSON + HTML

Endpoint

GET https://api.mediego.com/1.0/recommendations/json+html

Parameters

The parameters are the same as the request for recommendations in JSON.

Response

Success

The response is the same object returned by the JSON-only version of the request. In addition, an attribute html contains the HTML code representing the template filled with computed recommendations

{
    {
        "headers": {
            "muid": string, // Mediego user ID
            "engine": number, // Client ID
            "target": string, // Target property for links (<a>)
            "display_id": string, // ID of the display (recommendation request)
        },
        "items": [
         {
            "id": string, // ID of the recommendation
            "title": string,
            "description": string,
            "image": string,
            "link": string, // Link to the recommended item (tracking parameters are included)
            "metadata": object, // Object containing metadata of the item
            "categories": string[], // Categories of the recommended item
            "date": number // Timestamp of the recommendation
         },
         "html": string
        ]
    }
    
    
}

Error

{
    "error": string // Description of the error    
}