ratings
Retrieve app ratings distribution data from app stores to analyze user feedback patterns and rating trends for specific applications.
Instructions
Get app ratings distribution
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | iTunes trackId of the app | |
| appId | No | Bundle ID of the app | |
| country | No | Two-letter country code (default: us) | us |
Implementation Reference
- src/server.js:256-302 (handler)The main handler function for the 'ratings' tool. Fetches app details using buildRatingsUrl (which points to the app lookup endpoint), parses the app data, extracts ratings using parseRatings helper, and returns the ratings distribution as JSON./** * Ratings tool - Get app ratings distribution */ async function handleRatings(args) { try { const { id, appId, country = 'us' } = args; if (!id && !appId) { throw new Error('Either id or appId must be provided'); } const url = buildRatingsUrl({ id, appId, country }); const data = await fetchJSON(url); const app = parseApp(data); if (!app) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'App not found' }, null, 2), }, ], }; } const ratings = parseRatings(app); return { content: [ { type: 'text', text: JSON.stringify(ratings, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: error.message }, null, 2), }, ], isError: true, }; }
- src/server.js:1060-1081 (registration)Tool registration in the ListTools handler, defining the name, description, and input schema for the 'ratings' tool.{ name: 'ratings', description: 'Get app ratings distribution', inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'iTunes trackId of the app', }, appId: { type: 'string', description: 'Bundle ID of the app', }, country: { type: 'string', description: 'Two-letter country code (default: us)', default: 'us', }, }, }, },
- Helper function that parses the app data to extract total ratings count, average rating, and a placeholder histogram (not available from iTunes API).export function parseRatings(appData) { if (!appData || !appData.rating) { return { ratings: 0, histogram: { '1': 0, '2': 0, '3': 0, '4': 0, '5': 0, }, }; } // iTunes API doesn't provide histogram directly // We can only return the average and count // For histogram, we'd need to scrape the web page, which is more complex // For now, return what we have return { ratings: appData.rating.count || 0, average: appData.rating.average || null, histogram: { '1': 0, // Not available from API '2': 0, '3': 0, '4': 0, '5': 0, }, }; }
- src/endpoints/appStore.js:98-100 (helper)Helper function to build the URL for fetching ratings data; simply reuses the app detail lookup endpoint.export function buildRatingsUrl(params) { return buildAppUrl(params); }
- src/server.js:1453-1454 (registration)Dispatch registration in the CallToolRequestSchema switch statement, routing 'ratings' tool calls to handleRatings.case 'ratings': return await handleRatings(args);