Music Recommendations: A Detailed Overview of SoundStat API Extensions

Introduction: Enhanced Music Recommendation Capabilities

Finding the right music for specific moments, moods, or activities can be challenging in today's vast musical landscape. To address this need, we're introducing an extended set of SoundStat API endpoints that significantly enhance our recommendation capabilities.

These 12 new endpoints complement our existing recommendation system, offering developers more targeted ways to discover and suggest music based on specific parameters such as duration, mood, activity type, and musical characteristics. This expansion allows for more contextual and personalized music experiences in your applications.

From Basic to Advanced: The Evolution of Music Recommendations

Our standard recommendation endpoints have served well for general music discovery:

  • Similar track recommendations (/api/v1/recommendations/similar) - finds tracks with audio characteristics similar to a specified track
  • Feature-based recommendations (/api/v1/recommendations/by-features) - searches for tracks matching specific audio parameters
  • Mixed recommendations (/api/v1/recommendations/mixed) - combines characteristics from multiple tracks with target parameters

Our new endpoints build upon this foundation, offering more specialized and context-aware recommendation options.

Detailed Overview of New Endpoints

1. Duration-Based Recommendations (/api/v1/recommendations/duration)

What is it?

This endpoint finds tracks of specific duration, useful for creating playlists of exact length or selecting music for specific time intervals.

Key parameters:

  • min_duration_ms - minimum track duration in milliseconds (default 30000, or 30 seconds)
  • max_duration_ms - maximum track duration in milliseconds (default 600000, or 10 minutes)
  • genre - optional genre filter
  • limit - maximum number of recommendations (default 20)

Practical use cases:

  • Creating playlists for Pomodoro technique (25-minute work intervals)
  • Selecting tracks for fitness workouts with specific interval lengths
  • Building playlists for short breaks (5-10 minutes)
  • Finding music for timed meditation sessions
  • Creating playlists for journeys with known travel times

Imagine an app that automatically creates a playlist for your 30-minute run, with music perfectly matched to your pace and energy level. Or a program that selects exactly one hour of relaxing music for sleep.

2. Mood-Based Recommendations (/api/v1/recommendations/mood)

What is it?

This endpoint selects tracks that correspond to specific emotional states or moods, using combinations of audio characteristics such as valence (positivity), energy, and key.

Key parameters:

  • mood - mood type (happy, sad, energetic, relaxed, danceable)
  • genre - optional genre filter
  • limit - maximum number of recommendations

How moods are determined:

  • Happy - high valence (>0.7), medium to high energy (>0.5), major key
  • Sad - low valence (<0.4), low to medium energy (<0.5), minor key
  • Energetic - high energy (>0.8), fast tempo (>120 BPM)
  • Relaxed - low energy (<0.4), medium valence (0.3-0.7), high acousticness (>0.5)
  • Danceable - high danceability (>0.7), high energy (>0.6)

Practical use cases:

  • Mood improvement and stress-relief applications
  • Meditation and relaxation programs
  • Personalized playlists for different emotional states
  • Background music for gatherings, parties, or family events
  • Therapeutic applications using music to influence emotional states

Suppose you've had a tough day and want to lift your spirits. Using this endpoint, an application could offer a selection of positive tracks specifically chosen to improve mood, based on actual musical characteristics rather than just genre.

3. Activity-Based Recommendations (/api/v1/recommendations/activity)

What is it?

This endpoint selects tracks optimized for specific activities, whether it's working out, studying, sleeping, or partying.

Key parameters:

  • activity - activity type (workout, study, sleep, party, focus)
  • genre - optional genre filter
  • limit - maximum number of recommendations

How activity profiles are determined:

  • Workout - high energy (>0.8), fast tempo (>120 BPM), high danceability (>0.6), positivity (>0.5)
  • Study - medium energy (<0.5), high instrumentalness (>0.5), balanced valence (0.4-0.7)
  • Sleep - low energy (<0.3), slow tempo (<100 BPM), high acousticness (>0.5)
  • Party - high energy (>0.7), high danceability (>0.7), positivity (>0.6)
  • Focus - moderate energy (0.3-0.7), high instrumentalness (>0.4), balanced valence (0.3-0.7)

Practical use cases:

  • Fitness apps with automatic music selection based on workout type
  • Productivity programs with background music for work
  • Sleep and meditation apps with relaxing tracks
  • Event atmosphere creation applications
  • Integration with smart speakers for automatic music selection based on context

For example, a trainer in a fitness app could automatically select not just "energetic music," but tracks with specific characteristics proven to enhance workout efficiency.

4. Instrumental Recommendations (/api/v1/recommendations/instrumental)

What is it?

This endpoint specializes in finding instrumental tracks with minimal or no vocals.

Key parameters:

  • min_instrumentalness - minimum instrumentalness value (0-1, default 0.5)
  • genre - optional genre filter
  • limit - maximum number of recommendations

Practical use cases:

  • Background music for work or study that doesn't distract with lyrics
  • Meditative and relaxing playlists
  • Music for public spaces (cafes, stores)
  • Background accompaniment for videos, podcasts, or presentations
  • Sleep and relaxation playlists

Popular scenario: Many people find it difficult to concentrate on work when music contains lyrics. This endpoint allows creating ideal work playlists containing only instrumental music, taking into account user genre preferences.

5. Acoustic Recommendations (/api/v1/recommendations/acoustic)

What is it?

This endpoint selects tracks with predominance of acoustic instruments over electronic or synthesized sounds.

Key parameters:

  • min_acousticness - minimum acousticness value (0-1, default 0.5)
  • genre - optional genre filter
  • limit - maximum number of recommendations

Practical use cases:

  • Creating "organic" playlists with live sound
  • Music for cafes and restaurants with acoustic atmosphere
  • Relaxation and rest playlists
  • Background music for creative workshops and coworking spaces
  • Collections for "live music" enthusiasts

Imagine a small cafe wanting to create a specific atmosphere with acoustic music. Using this endpoint, an ideal playlist consisting only of tracks with high acousticness could be created without manually checking each track.

6. Parameter Progression (/api/v1/recommendations/progression)

What is it?

This advanced endpoint creates a sequence of tracks with a gradually changing musical parameter. For example, a playlist with smooth increase in energy or tempo from beginning to end.

Key parameters:

  • parameter - parameter for progression (energy, tempo, danceability, valence)
  • direction - direction of change (increase, decrease)
  • steps - number of tracks in progression (2-10)
  • start_value - initial parameter value (optional)
  • genre - optional genre filter

Practical use cases:

  • Running playlists with gradual tempo increase
  • Workouts with warm-up, active phase, and cool-down
  • Meditations with changing intensity
  • DJ sets with smooth transitions between moods
  • Sleep programs with gradual energy reduction

For example, for a run you could create a playlist starting with 100 BPM tracks for warm-up, gradually increasing to 160 BPM for the active phase, and decreasing again for cool-down. All automatically, without manually selecting tracks.

7. Musical Compatibility (/api/v1/recommendations/compatible)

What is it?

This endpoint finds tracks that are musically compatible with a specified track by key, tempo, or both parameters, allowing creation of playlists with harmonious transitions.

Key parameters:

  • track_id - ID of the source track
  • compatibility_type - compatibility type (key, bpm, both)
  • limit - maximum number of recommendations
  • min_popularity - minimum track popularity (optional)

Musical compatibility details:

  • Key - tracks in the same key, as well as harmonically related keys (dominant, subdominant, parallel minor/major)
  • BPM (Tempo) - tracks with similar tempo (±5%), or with tempo twice as fast or twice as slow as the original
  • Both - tracks compatible in both key and tempo

Practical use cases:

  • Professional DJ tools for creating seamless mixes
  • Creating harmonious, good-sounding playlists
  • Automatic formation of continuous music streams
  • Educational applications on music theory
  • Personal playlists for parties with smooth transitions

This endpoint is especially valuable for DJs and music enthusiasts. Imagine wanting to create a two-hour mix with smooth transitions between tracks. Instead of manually analyzing the key and tempo of each track, you can use this endpoint to automatically find compatible tracks.

8. Contrast Recommendations (/api/v1/recommendations/contrast)

What is it?

This non-standard endpoint finds tracks that deliberately contrast with a specified track in selected parameters, creating interesting musical combinations and helping expand musical horizons.

Key parameters:

  • track_id - ID of the source track
  • contrast_features - list of parameters for contrast (default energy and valence)
  • limit - maximum number of recommendations

Practical use cases:

  • Creating diverse playlists with interesting contrasts
  • Overcoming the "echo chamber" of musical preferences
  • Exploring new musical experiences
  • Educational applications on music theory and composition
  • Creative projects based on contrasts

Contrast recommendations are useful when users want to step outside their usual musical comfort zone. For example, after a series of energetic dance tracks, an application could offer a few calm, relaxing compositions to create balance.

9. Cross-Genre Recommendations (/api/v1/recommendations/cross-genre)

What is it?

This innovative endpoint finds tracks from other genres but with similar audio characteristics. It helps discover new genres while maintaining familiar sound.

Key parameters:

  • track_id - ID of the source track
  • exclude_genres - list of genres to exclude
  • limit - maximum number of recommendations

Practical use cases:

  • Introducing listeners to new genres through familiar sound profiles
  • Creating diverse but harmonious playlists
  • Music educational programs
  • Expanding users' musical horizons
  • Tools for music producers seeking cross-genre inspiration

For example, an electronic music lover might discover jazz through tracks with similar rhythmic patterns or energy levels. Or a rock fan might get acquainted with classical music through works with similar dynamics and emotionality.

10. Time-of-Day Recommendations (/api/v1/recommendations/time-of-day)

What is it?

This contextual endpoint selects tracks optimal for specific times of day, considering natural rhythms of activity and mood.

Key parameters:

  • time - time of day (morning, afternoon, evening, night)
  • genre - optional genre filter
  • limit - maximum number of recommendations

Time of day profiles:

  • Morning - moderate energy (0.5-0.7), positive valence (>0.6), medium tempo (90-120 BPM)
  • Afternoon - increased energy (0.6-0.8), positive valence (>0.5), fast tempo (100-130 BPM)
  • Evening - moderate energy (0.4-0.7), balanced valence (0.4-0.7), medium tempo (85-110 BPM)
  • Night - reduced energy (<0.5), increased danceability (>0.5), slow tempo (<100 BPM)

Practical use cases:

  • Smart alarms with time-appropriate music
  • Integration with smart homes for automatic music atmosphere changes
  • Applications for healthy daily routine formation
  • Music streaming services with contextual recommendations
  • Business solutions for creating atmosphere in shopping centers and restaurants

Imagine a smart speaker that offers energetic, positive tracks in the mornings to help you wake up, and automatically switches to calmer, relaxing music in the evening.

11. Hidden Gems (/api/v1/recommendations/hidden-gems)

What is it?

This endpoint specializes in finding quality but little-known tracks, helping discover new music that hasn't yet received wide recognition.

Key parameters:

  • similar_to_track_id - optional reference track
  • max_popularity - maximum popularity index (0-100, default 40)
  • genre - optional genre filter
  • limit - maximum number of recommendations

Practical use cases:

  • Curator applications for true music lovers
  • Platforms for promoting independent musicians
  • Music blogs and channels focusing on new artists
  • Personal playlists for unique music enthusiasts
  • Tools for music scouts and labels

This endpoint is ideal for those who love discovering new artists and being "ahead of the trend." Users can find high-quality tracks with characteristics similar to their favorite music, but from little-known artists who haven't yet received wide recognition.

12. Beat Structure Recommendations (/api/v1/recommendations/beat-structure)

What is it?

This specialized endpoint selects tracks with specific rhythmic structure characteristics, such as beat regularity, which is especially important for dance music or workouts.

Key parameters:

  • min_regularity - minimum beat regularity value (0-1, default 0.7)
  • tempo_min - minimum tempo (BPM)
  • tempo_max - maximum tempo (BPM)
  • genre - optional genre filter
  • limit - maximum number of recommendations

Practical use cases:

  • Professional DJ tools and mixing programs
  • Dance applications with precise movement synchronization
  • Workout programs with rhythmic exercises
  • Rehabilitation programs with rhythm therapy
  • Applications for drummers and rhythm section musicians

For example, a dance application could use this endpoint to find tracks with a very stable beat for a specific dance style. Or a fitness program could select tracks with regular rhythm for synchronizing movements with music.

Combining Endpoints for Unique Musical Experiences

The true power of the new endpoints is revealed when combining them. Here are some examples:

Smart Alarm:

  • Uses time-of-day to select morning tracks
  • Combines with progression for gradual energy increase
  • Filters results through duration for precise time control

Meditation Application:

  • Starts with activity to find relaxing tracks
  • Applies instrumental to remove distracting vocals
  • Uses acoustic to create organic sound

DJ Tool:

  • Uses compatible to find tracks harmonizing with the current one
  • Applies beat-structure to ensure stable rhythm
  • Adds variety using cross-genre

Personal Trainer:

  • Starts with progression for warm-up and gradual intensity building
  • Maintains high intensity using activity (workout)
  • Completes workout using mood (relaxed) for stretching

Technical Aspects of Working with New Endpoints

All new endpoints follow a unified structure and operating principles:

  • Authentication: Each request requires a valid API key, transmitted in the X-API-Key header
  • Rate limiting: The API has built-in limitation on the number of simultaneous requests
  • Response format: All endpoints return JSON with a unified structure {"track_ids": ["id1", "id2", ...]}
  • Pagination: The limit parameter controls the number of returned results
  • Error handling: The API returns standard HTTP status codes and detailed error messages

Request Examples

Example request to get happy tracks:

POST /api/v1/recommendations/mood
X-API-Key: your-api-key
Content-Type: application/json

{
  "mood": "happy",
  "limit": 10
}

Example request to get workout tracks:

POST /api/v1/recommendations/activity
X-API-Key: your-api-key
Content-Type: application/json

{
  "activity": "workout",
  "genre": "rock",
  "limit": 15
}

Real-World Usage Examples

Example 1: Productivity Music Application

Imagine an application that helps users be more productive throughout the workday:

  • Morning (9:00): Uses /api/v1/recommendations/time-of-day with "morning" parameter for an energetic start
  • Work (10:00-12:00): Switches to /api/v1/recommendations/instrumental with high min_instrumentalness for concentration
  • Lunch (12:00-13:00): Offers tracks via /api/v1/recommendations/mood with "happy" parameter for mood lifting
  • Afternoon slump (14:00-16:00): Uses /api/v1/recommendations/activity with "focus" parameter to combat drowsiness
  • End of day (17:00): Transitions to /api/v1/recommendations/progression for gradual energy reduction

Example 2: Fitness Application with Personalized Music

  • Warm-up: /api/v1/recommendations/progression with increasing tempo and energy
  • Cardio: /api/v1/recommendations/beat-structure with high regularity for rhythmic exercises
  • Strength training: /api/v1/recommendations/activity with "workout" parameter and high energy
  • Stretching and cool-down: /api/v1/recommendations/acoustic for a calmer workout conclusion

Example 3: Music Explorer for Discovery Enthusiasts

  • Starting track: User selects a favorite track
  • Similar tracks from other genres: /api/v1/recommendations/cross-genre expands musical horizons
  • Lesser-known gems: /api/v1/recommendations/hidden-gems offers tracks from new artists
  • Contrasting discoveries: /api/v1/recommendations/contrast offers completely new sounds

Conclusion: Practical Applications of Enhanced Music Recommendations

The SoundStat API extension offers developers powerful new tools for creating more tailored music experiences. These 12 new endpoints provide specific functionality for different contexts - from fitness and productivity apps to meditation tools and music discovery services.

By integrating these specialized recommendation capabilities, you can enhance your applications with more relevant music suggestions based on duration, mood, activity, time of day, and many other contextual factors. This allows for creating more engaging user experiences where music truly complements the intended purpose of your application.

We encourage developers to explore these new endpoints and combine them in creative ways. The documentation provides all necessary details to get started, and our support team is available to help with integration questions.