API Endpoint: GET /tracks
Relevant source files
The following files were used as context for generating this wiki page:
The GET /tracks endpoint is a core component of the Spotify API Data Collector system, designed to expose collected musical metadata through a RESTful interface. Its primary purpose is to allow users to query, filter, and paginate through tracks stored in the local SQLite database that were harvested via the Spotify Web API.
This endpoint serves as a read-access layer for the data persisted by the crawler and processed by the system's data management logic. It supports filtering by specific years (2020-2024) and minimum popularity scores, ensuring that consumers of the API can retrieve targeted subsets of the musical data.
Sources: app/api.py:64-83, README.md:12-25
Endpoint Architecture and Data Flow
The architecture follows a standard FastAPI pattern where the API layer interacts with a database utility layer to fetch records. When a request is made to /tracks, the application loads the data using a helper function that leverages the database connection.
Request Handling Flow
The following diagram illustrates the sequence of operations from the initial HTTP request to the final JSON response.
The endpoint first retrieves all records from the database and then applies Python-based filtering and slicing for pagination.
Sources: app/api.py:20-30, app/api.py:90-112, app/database.py:108-113
Query Parameters
The endpoint accepts several optional query parameters to refine the results returned to the client.
| Parameter | Type | Description | Constraints |
|---|---|---|---|
limit | Integer | Maximum number of tracks to return | Min: 1, Max: 1000 |
offset | Integer | Number of records to skip for pagination | Min: 0, Default: 0 |
year | Integer | Filter tracks by release year | 2020 - 2024 |
min_popularity | Integer | Filter by minimum track popularity score | 0 - 100 |
Sources: app/api.py:65-70, README.md:104-108
Data Structure and Model
The tracks returned by the endpoint conform to the system's internal Track data model. This model captures both track-specific information and enriched artist details.
Track Schema (Table: tracks)
The database utilizes indexes on year, artist_name, and track_popularity to optimize query performance, although the current implementation of the /tracks endpoint performs additional filtering in-memory after fetching from the database.
Sources: app/track.py:7-21, app/database.py:17-33, README.md:40-54
Implementation Details
The core logic resides in app/api.py. The endpoint uses the load_tracks_from_db helper function to interface with app/database.py.
@app.get("/tracks")
async def get_tracks(
limit: Optional[int] = Query(None, ge=1, le=1000),
offset: Optional[int] = Query(0, ge=0),
year: Optional[int] = Query(None, ge=2020, le=2024),
min_popularity: Optional[int] = Query(None, ge=0, le=100)
):
tracks = load_tracks_from_db()
# Filtering logic
if year is not None:
tracks = [t for t in tracks if int(t.get('year', 0)) == year]
if min_popularity is not None:
tracks = [t for t in tracks if int(t.get('track_popularity', 0)) >= min_popularity]
# Pagination logic
total = len(tracks)
if offset is not None:
tracks = tracks[offset:]
if limit is not None:
tracks = tracks[:limit]
return {
"total": total,
"limit": limit,
"offset": offset,
"count": len(tracks),
"tracks": tracks
}
Sources: app/api.py:73-112
Response Format
The endpoint returns a JSON object containing metadata about the result set and the actual track records.
total: The total number of tracks matching the filters before pagination.limit: The maximum number of tracks requested.offset: The starting point in the result set.count: The actual number of tracks returned in the current response.tracks: A list of track objects containing metadata liketrack_name,artist_name, andtrack_popularity.
Sources: app/api.py:106-112, test/test_api.py:108-114
Summary
The GET /tracks endpoint provides a flexible interface for accessing the Spotify data stored in the SQLite backend. By combining database retrieval with FastAPI's query parameter validation, it allows for efficient data exploration based on year and popularity, supporting the project's goal of analyzing popular music trends between 2020 and 2024.