Building Predictive Recommendation API

Welcome to the final lesson of this course! So far, you have learned how to prepare training data, train a machine learning model, and use that model to score tracks for users. In this lesson, you will bring everything together by building an API endpoint that delivers personalized music recommendations using your trained model.

Predictive recommendations are a key feature in modern music apps. Instead of just suggesting tracks that are similar to what a user has already listened to, predictive recommendations use machine learning to guess what a user will like — even if they have never heard it before. This makes the listening experience more personal and engaging.

By the end of this lesson, you will know how to create an API endpoint that returns a list of tracks your model predicts a user will enjoy.

This endpoint builds on components you've already implemented:

• Trained ML model: Trained on past listening data.
• Track database: Used to fetch details of recommended tracks.
• User listening history: Used to avoid recommending already-played songs.
• recommend_tracks_by_prediction() function: Uses the model to generate top-N track IDs for a user.

In previous lessons, you learned how to use a machine learning model to score tracks for a user. Predictive recommendations take this a step further. Instead of just finding tracks that are similar to what a user has already listened to, you use your trained model to predict which tracks a user is most likely to enjoy — even if they have never listened to them before.

Here’s how it works:

• The model takes in features about the user and the track.
• It outputs a confidence score for each track, showing how likely the user is to enjoy it.
• You sort the tracks by their scores and recommend the top ones.

This is different from similarity-based recommendations, which only look at how close tracks are to each other in terms of features or listening patterns. Predictive recommendations use patterns learned from all users to make smarter guesses.

Now, let’s build the new API endpoint: /api/recommendations/predictive/<user_id>. This endpoint will return a list of tracks that your model predicts the user will like.

Here is the main code for the endpoint:

@app.route('/api/recommendations/predictive/<user_id>', methods=['GET'])
def get_predictive_recommendations_endpoint(user_id: str):
    """API endpoint for ML model-based track recommendations."""
    try:
        top_n_str = request.args.get('top_n', default='5')
        top_n = int(top_n_str)
        if top_n <= 0:
            return jsonify({"error": "top_n must be a positive integer"}), 400
    except ValueError:
        return jsonify({"error": "top_n must be a valid integer"}), 400

    recommended_track_ids = recommend_tracks_by_prediction(user_id, top_n=top_n)
    
    if not recommended_track_ids:
        return jsonify({
            "user_id": user_id,
            "recommendations": [],
            "message": "No predictive recommendations available (model might be unavailable or no suitable tracks)."
        }), 200

    recommended_tracks_details = []
    for track_id in recommended_track_ids:
        track_details = get_track_by_id(track_id)
        if track_details:
            recommended_tracks_details.append(track_details)
            
    return jsonify({
        "user_id": user_id,
        "recommendations": recommended_tracks_details
    })

Let’s break down what happens here:

• Step 1: Validate Input: The top_n query parameter controls how many recommendations are returned. It's parsed and checked to ensure it's a valid positive integer. If not, the endpoint returns a 400 Bad Request.
• Step 2: Generate Recommendations: The function recommend_tracks_by_prediction(user_id, top_n) is called. This:
  • Loads the trained model.
  • Scores all unlistened tracks.
  • Sorts them and returns the top N track IDs.
• Step 3: Enrich with Track Details: Each track ID is passed to get_track_by_id() to fetch full metadata (title, artist, etc.).
• Step 4: Return Response: A JSON object with the user_id and list of full track objects is returned.

Example Output:

If the user asks for 3 recommendations, the response might look like this:

{
  "user_id": "user123",
  "recommendations": [
    {"id": "trackA", "title": "Song A", "artist": "Artist 1"},
    {"id": "trackB", "title": "Song B", "artist": "Artist 2"},
    {"id": "trackC", "title": "Song C", "artist": "Artist 3"}
  ]
}

Behind the Scenes: How recommend_tracks_by_prediction() Works This helper function: - Loads the trained model (from disk). - Gets all available tracks and filters out tracks already played by the user. - Calls predict_affinity_scores_for_user() to assign confidence scores. - Sorts tracks by score and returns the top-N unplayed track IDs.

By doing this work in a separate function, the endpoint logic stays clean and testable.

This makes it easy for your app or website to show personalized music suggestions to each user.

A good API should handle problems gracefully. Here are some situations your endpoint is ready for:

• No Model Available:
  If the model is missing or not trained yet, the endpoint returns an empty list and a helpful message.

  JSON

  {
    "user_id": "user123",
    "recommendations": [],
    "message": "No predictive recommendations available (model might be unavailable or no suitable tracks)."
  }

• Invalid top_n Parameter:
  If the user asks for zero or a negative number of recommendations, or provides a non-integer value, the API returns an error message.

  JSON

  {
    "error": "top_n must be a positive integer"
  }

• No Recommendations Found:
  If the model cannot find any suitable tracks for the user, the API returns an empty list with a message.

These checks make your API more reliable and user-friendly.

Test 1 — No Model Available

Model file not found...  
✅ Passed: No model scenario handled gracefully.

This confirms the fallback logic works. If the model file is missing or loading fails, the system returns a safe response with:

{
  "user_id": "user123",
  "recommendations": [],
  "message": "No predictive recommendations available..."
}

Test 2 — Invalid top_n Parameter

Status Code: 400  
Response JSON: {"error": "top_n must be a positive integer"}  
✅ Passed: Correct handling of invalid top_n.

This shows the input validation is functioning. If top_n=0 or something non-numeric is sent, the system blocks the request with a clear error message.

Test 3 — Successful Recommendation

Status Code: 200  
Response JSON: {'recommendations': [{'id': 'b'}], 'user_id': 'user123'}  
✅ Passed: Recommendation returned successfully.

This confirms the full flow: model loaded, predictions made, track details fetched, and results returned — all working together.

In this lesson, you learned how to build an API endpoint that delivers personalized, predictive music recommendations using a trained machine learning model. You saw how to handle user input, generate recommendations, and deal with errors and edge cases.

Congratulations on reaching the end of the course! You now have the skills to prepare data, train a model, score tracks, and build a real-world recommendation API. Take a moment to celebrate your progress, and when you are ready, try out the practice exercises to reinforce what you have learned. Well done!