list
Retrieve app rankings from app stores, including top free, paid, and grossing charts by country and genre.
Instructions
Get app rankings (top free, paid, or grossing)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chart | No | Chart type: topfreeapplications, toppaidapplications, or topgrossingapplications | topfreeapplications |
| country | No | Two-letter country code (default: us) | us |
| genre | No | Genre ID or "all" (default: all) | all |
| limit | No | Number of results (default: 200) |
Implementation Reference
- src/server.js:166-208 (handler)The main handler function for the 'list' tool, responsible for building the request URL, fetching data, parsing the app list, and formatting the response./** * List tool - Get app rankings (top free, paid, grossing) */ async function handleList(args) { try { const { chart = 'topfreeapplications', category = 'all', country = 'us', genre = 'all', limit = 200, } = args; const url = buildListUrl({ chart, category, country, genre, limit }); const data = await fetchJSON(url); // Use parseList for RSS feed format, fallback to parseApps for JSON format const apps = data.feed ? parseList(data) : parseApps(data); return { content: [ { type: 'text', text: JSON.stringify({ chart, country, results: apps, count: apps.length, }, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: error.message }, null, 2), }, ], isError: true, }; } }
- src/server.js:997-1026 (registration)The tool registration object returned in ListToolsRequestSchema response, defining the 'list' tool's metadata, description, and input schema for validation.{ name: 'list', description: 'Get app rankings (top free, paid, or grossing)', inputSchema: { type: 'object', properties: { chart: { type: 'string', description: 'Chart type: topfreeapplications, toppaidapplications, or topgrossingapplications', default: 'topfreeapplications', enum: ['topfreeapplications', 'toppaidapplications', 'topgrossingapplications'], }, country: { type: 'string', description: 'Two-letter country code (default: us)', default: 'us', }, genre: { type: 'string', description: 'Genre ID or "all" (default: all)', default: 'all', }, limit: { type: 'number', description: 'Number of results (default: 200)', default: 200, }, }, }, },
- src/parsers/appStore/list.js:12-56 (helper)Supporting parser utility that processes raw RSS data from App Store rankings into structured app objects, used by the handleList function.export function parseList(data) { if (!data || !data.feed) { return []; } const apps = []; try { // RSS feed format has entries in feed.entry if (data.feed.entry && Array.isArray(data.feed.entry)) { for (const entry of data.feed.entry) { // Convert RSS entry to app format const app = { trackId: extractId(entry), bundleId: extractBundleId(entry), trackName: extractTitle(entry), artistName: extractArtist(entry), artistId: extractArtistId(entry), description: extractDescription(entry), price: extractPrice(entry), currency: 'USD', averageUserRating: extractRating(entry), userRatingCount: extractRatingCount(entry), artworkUrl100: extractIcon(entry), artworkUrl512: extractIcon(entry), screenshotUrls: extractScreenshots(entry), primaryGenreName: extractCategory(entry), releaseDate: extractReleaseDate(entry), kind: 'software', }; // Use parseApp to normalize const lookupData = { results: [app] }; const normalizedApp = parseApp(lookupData); if (normalizedApp) { apps.push(normalizedApp); } } } } catch (error) { console.error('Error parsing App Store list:', error); } return apps; }
- src/endpoints/appStore.js:150-173 (helper)Utility function that constructs the specific URL for App Store chart/ranking endpoints based on parameters, called by the handler.* Builds a list/ranking URL * @param {Object} params - List parameters * @returns {string} */ export function buildListUrl(params) { const { category = 'all', country = 'us', genre = 'all', limit = 200, chart = 'topfreeapplications', // topfreeapplications, toppaidapplications, topgrossingapplications } = params; const queryParams = new URLSearchParams({ country: country, limit: limit.toString(), }); if (genre !== 'all') { queryParams.append('genre', genre); } return `${ITUNES_BASE}/${country}/rss/${chart}/limit=${limit}/json`; }