gp_list
Retrieve Google Play Store app rankings for top free, paid, grossing, and trending apps by specifying country, category, and result count.
Instructions
[Google Play] Get app rankings (top free, paid, grossing)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection | No | Collection type: topselling_free, topselling_paid, topgrossing, movers_shakers | topselling_free |
| category | No | Category ID (default: APPLICATION) | APPLICATION |
| country | No | Two-letter country code (default: us) | us |
| lang | No | Language code (default: en) | en |
| num | No | Number of results (default: 60) |
Implementation Reference
- src/server.js:612-651 (handler)The primary handler function for the 'gp_list' tool. It destructures input args, builds the Google Play list URL, fetches the HTML, parses the app list using parseGPList, and returns a formatted JSON response.async function handleGPList(args) { try { const { collection = 'topselling_free', category = 'APPLICATION', country = 'us', lang = 'en', num = 60, } = args; const url = buildGPListUrl({ collection, category, country, lang, num }); const html = await fetchText(url); const apps = parseGPList(html); return { content: [ { type: 'text', text: JSON.stringify({ collection, category, 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:1237-1267 (schema)Input schema defining parameters, types, defaults, and validation (e.g., enum for collection) for the gp_list tool.inputSchema: { type: 'object', properties: { collection: { type: 'string', description: 'Collection type: topselling_free, topselling_paid, topgrossing, movers_shakers', default: 'topselling_free', enum: ['topselling_free', 'topselling_paid', 'topgrossing', 'movers_shakers'], }, category: { type: 'string', description: 'Category ID (default: APPLICATION)', default: 'APPLICATION', }, country: { type: 'string', description: 'Two-letter country code (default: us)', default: 'us', }, lang: { type: 'string', description: 'Language code (default: en)', default: 'en', }, num: { type: 'number', description: 'Number of results (default: 60)', default: 60, }, }, },
- src/server.js:1234-1268 (registration)Tool registration entry in the ListToolsRequestSchema handler, including name, description, and schema.{ name: 'gp_list', description: '[Google Play] Get app rankings (top free, paid, grossing)', inputSchema: { type: 'object', properties: { collection: { type: 'string', description: 'Collection type: topselling_free, topselling_paid, topgrossing, movers_shakers', default: 'topselling_free', enum: ['topselling_free', 'topselling_paid', 'topgrossing', 'movers_shakers'], }, category: { type: 'string', description: 'Category ID (default: APPLICATION)', default: 'APPLICATION', }, country: { type: 'string', description: 'Two-letter country code (default: us)', default: 'us', }, lang: { type: 'string', description: 'Language code (default: en)', default: 'en', }, num: { type: 'number', description: 'Number of results (default: 60)', default: 60, }, }, }, },
- src/server.js:1470-1471 (registration)Dispatch case in the CallToolRequestSchema handler that routes 'gp_list' calls to handleGPList.case 'gp_list': return await handleGPList(args);
- src/endpoints/googlePlay.js:111-129 (helper)Helper function buildListUrl (imported as buildGPListUrl) that constructs the Google Play category/collection ranking URL.export function buildListUrl(params) { const { category = 'APPLICATION', collection = 'topselling_free', // topselling_free, topselling_paid, topgrossing, movers_shakers country = 'us', lang = 'en', num = 60, } = params; const queryParams = new URLSearchParams({ category: category, collection: collection, gl: country, hl: lang, num: num.toString(), }); return `${GOOGLE_PLAY_BASE}/store/apps/category/${category}/collection/${collection}?${queryParams.toString()}`; }
- src/parsers/googlePlay/list.js:12-15 (helper)Parser function parseList (imported as parseGPList) that extracts app data from list HTML by delegating to parseSearch.export function parseList(html) { // List pages use similar structure to search results return parseSearch(html); }