Song Search Examples & API Documentation

Live Examples

1. Simple Search (Fast)

2. SOUNDEX Search (Phonetic)

SOUNDEX search uses SOUNDEX phonetic matching to find songs that sound similar to your search term.

3. Advanced Search (With Scoring)

Advanced search combines exact matching, prefix matching, contains matching, and SOUNDEX fuzzy matching with weighted scoring. Shows search scores when enabled.

4. Advanced Search (With Filters)

Filtered search demonstrates how to combine search queries with source, metadata status, package status, catalog status, and date filters. Date format: MM/DD/YY (e.g., 01/15/22).

API Documentation

GET/api/v1/songs/search/

Search for songs using various search algorithms and filters.

Query Parameters

Parameter Type Required Description
catalog_status string No Filter by catalog status (e.g., "Accepted", "Rejected", "Review")
created_after string No Filter songs created after this date (YYYY-MM-DD format)
created_before string No Filter songs created before this date (YYYY-MM-DD format)
include_scores boolean No Include search scores in results (accepts: 1/0, true/false, yes/no, on/off)
limit integer No Maximum number of results (default: 20, max: 100)
metadata_status string No Filter by metadata processing status (e.g., "Processed", "ERROR")
offset integer No Number of results to skip for pagination (default: 0)
package_status string No Filter by package status (e.g., "Not in Playlist", "Packaged")
query string Yes Search query string (minimum 3 characters)
source string No Filter by source (exact match with source field)
type string No Search type: simple (default), advanced, or soundex
q string No DEPRECATED: Use "query" instead (backward compatibility)
status string No DEPRECATED: Use "metadata_status" instead (backward compatibility)
timestamp_after string No DEPRECATED: Use "created_after" instead (backward compatibility)
timestamp_before string No DEPRECATED: Use "created_before" instead (backward compatibility)

Search Types

  • simple - Fast search using combined fields with flexible word order
  • advanced - Full scoring with exact, prefix, contains, and SOUNDEX matching plus edit distance boost
  • soundex - Phonetic matching using SOUNDEX algorithm

Success Response

200 OK
[ { "song_id": 5392, "song_uuid": "1a2b3c4d-5e6f-7890-abcd-ef1234567890", "song_name": "Blackbird - Remastered 2009", "artist_name": "The Beatles", "album_name": "The Beatles (Remastered)", "spotify_id": "5jgFfDIR6FR0gvlA56Nakr", "source": "[\"Pop 100\"]", "status": "Processed", "metadata_status": "Processed", "package_status": "Not in Playlist", "catalog_status": "Accepted", "score": 1440 }, { "song_id": 7393, "song_uuid": "2b3c4d5e-6f78-9abc-def0-123456789012", "song_name": "Hey Jude - 2015 Mix", "artist_name": "The Beatles", "album_name": "The Beatles 1967 – 1970 (2023 Edition)", "spotify_id": "1RP85mAmvJ8baqjP53kFJu", "source": "[\"Pop 100\"]", "status": "Processed", "metadata_status": "Processed", "package_status": "Packaged", "catalog_status": "Accepted", "score": 1440 } ]

Error Responses

400 Bad Request
{ "error": "Query parameter 'q' is required" }
400 Bad Request
{ "error": "Query must be at least 2 characters long" }
500 Internal Server Error
{ "error": "Database connection failed" }

GET/api/v1/songs/search/?filters=1

Get available filter options for search queries.

Success Response

200 OK
{ "sources": [ "[\"All time Top\"]", "[\"Current Top\"]", "[\"Editors Pick\"]", "[\"Founders Pick\"]", "[\"Listeners Pick\"]", "[\"Pop 100\"]", "[]", "Fast Find", "internal" ], "statuses": [ "Processed", "ERROR", "Pending" ], "metadata_statuses": [ "Processed", "ERROR", "Pending" ], "package_statuses": [ "Not in Playlist", "Packaged", "In Playlist" ], "catalog_statuses": [ "Accepted", "Rejected", "Review", "Pending" ], "timestamp_range": { "min_timestamp": "2025-07-03 14:34:50", "max_timestamp": "2025-07-07 17:14:09" } }

Error Response

500 Internal Server Error
{ "error": "Filter options unavailable" }

GET/api/v1/songs/search/?stats=1

Get database statistics and cache information.

Success Response

200 OK
{ "total_entries": 191083, "unique_songs": 189429, "unique_artists": 45231, "unique_albums": 67892, "spotify_entries": 187234, "uuid_entries": 191083 }

Error Response

500 Internal Server Error
{ "error": "Stats unavailable" }

Example Usage

Basic Search

GET /api/v1/songs/search/?query=beatles&limit=5

Advanced Search with Scores

GET /api/v1/songs/search/?query=beatles&type=advanced&include_scores=true&limit=10

Filtered Search

GET /api/v1/songs/search/?query=music&type=advanced&source=[%22Pop%20100%22]&metadata_status=Processed&package_status=Not%20in%20Playlist&created_after=2025-01-01

Multiple Status Filters

GET /api/v1/songs/search/?query=beatles&metadata_status=Processed&catalog_status=Accepted

Pagination

GET /api/v1/songs/search/?query=beatles&limit=10&offset=20

Phonetic Search

GET /api/v1/songs/search/?query=beetles&type=soundex&limit=5

Boolean Parameters

GET /api/v1/songs/search/?query=beatles&include_scores=1 (or true, yes, on)

Additional Notes