gp_list
Retrieve Google Play Store app rankings for top free, paid, grossing, and trending apps by category and country.
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 main handler function for the 'gp_list' tool. It extracts parameters from args, constructs the Google Play list URL, fetches the HTML, parses it using parseGPList, and returns the list of apps in JSON format.
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:1234-1268 (schema)The input schema for the 'gp_list' tool, defining parameters such as collection, category, country, lang, and num with their types, descriptions, defaults, and enums.
{ 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)Registration in the tool dispatch switch statement: routes calls to 'gp_list' to the handleGPList function.
case 'gp_list': return await handleGPList(args); - src/parsers/googlePlay/list.js:12-15 (helper)Helper parser function parseList (imported as parseGPList) that extracts app data from Google Play list page HTML by reusing the search parser.
export function parseList(html) { // List pages use similar structure to search results return parseSearch(html); } - src/endpoints/googlePlay.js:111-111 (helper)Helper function buildListUrl (imported as buildGPListUrl) that constructs the Google Play list/ranking URL based on parameters.
export function buildListUrl(params) {