HQ-ICON: pulling App Store icons by name, link or app id

The whole interface is a query string

The tool is a single web page, and everything it does is expressed in the URL.

The parameter table is the specification. `name` takes the application name, the store link or the App ID, with no default. `country` is the country or region with codes like cn, us, jp and kr, and it defaults to cn. `entity` selects the search object, one of software, iPadSoftware or desktopSoftware, defaulting to software. `limit` is the search result cap, from 1 to 200, defaulting to 18. `cut` chooses the icon style, where 0 is the original image, 1 is standard and 2 is official, defaulting to 2. `resolution` is 256, 512 or 1024, defaulting to 512. And `format` is jpeg, png or webp, defaulting to png.

A complete example from the README puts those together, requesting Google in the US storefront as software with a limit of 18, the official cut at 1024 resolution and webp output, using the query string name=Google&country=us&entity=software&limit=18&cut=2&resolution=1024&format=webp.

Designing the interface as URL parameters has a practical consequence that is easy to miss. Because the state is entirely in the query string, a result is a link you can bookmark, paste into a message, or drop into a script, and there is no session to keep and nothing to authenticate against.

The `cut` option is the one that carries the most design weight. Choosing between the original artwork, a standard variant and the official one is a question about which image the store actually serves for the listing, and the fact that the tool exposes all three as a URL parameter means the choice is per-request rather than per-installation.

Region comes from the link, and an explicit country wins

The region handling is the part of the README with the most specific rules, and getting it wrong produces a result that looks broken rather than wrong.

The search box accepts an application name, a store link, or an App ID. When you paste a link such as `https://apps.apple.com/sg/app/siri/id6758482875`, the region in that link is used for the query, so this example queries the Singapore storefront for Siri. When you type only the App ID, the currently selected region is used instead. And a `country` parameter written explicitly in the page URL takes precedence over the region in the App Store link.

That precedence order is a sensible design, since the URL is the shareable artifact and the link is the pasted input. It also means the same tool serves two regions at once if you paste a Japanese link but the URL says country=us, and the URL wins.

The README then states the failure case directly. Some applications are not on sale in all regions, and when you cannot find an app in another region you should switch regions or paste a link for the corresponding region. This is not a limitation of the tool but of the store's catalog, which is regional by design, and it is worth understanding before assuming a missing app means a missing ID.

The parameter table's own header row gives the country codes as cn, us, jp and kr among others, and the acknowledgements credit a Country Codes reference, so the set of supported values is the standard ISO-style code list rather than a custom set.

It sits on Apple's search API, not on the store page

The acknowledgements name the pieces the tool is built from, and one of them tells you the whole architecture.

The stack is React and Vite, with a Country Codes reference for the region list, an hq-icon project by f48vj, and the Search API from Apple's performance partners documentation. The project that the tool is based on is called hq-icon, which is the name Apple's search API itself uses, so this is a front end over that API rather than something that scrapes the store's HTML.

That distinction is worth holding onto, because it determines how the tool behaves. A tool that parses store pages has to guess at the markup and breaks when Apple changes it. A tool that calls the search API is asking for structured data, and the fields it returns, an app name, an id, an artwork URL, a seller, a genre, come back as data. The icon in the response is a URL to an Apple-hosted image, and the `cut` and `resolution` parameters are then applied to that image rather than to a scraped preview.

The README does not describe caching, rate limiting or retry behavior for the API calls, and it does not state whether there is a server component at all. The `private` flag in the package manifest and the presence of a `public/` directory alongside `src/` suggest a static build, in which case the search would run from the browser and the region and format options would be handled client side.

What that means in practice is that this is a tool with one upstream dependency that the project does not control, and the README's silence about failure modes is a gap a user has to fill by trying it.

A Vite and React app with a node test runner

The repository layout is small and says what kind of project this is.

The manifest names the package `hq_icon` at version 1.1.3, with `"type": "module"` and `"private": true`, and the top level entries are `index.html`, `src/`, `public/`, `test/`, a `vite.config.js`, a `package.json` and the usual repository files.

The scripts are the four you would expect from a Vite project:

    "dev": "vite --host",
    "build": "vite build",
    "preview": "vite preview",
    "test": "node --test test/*.test.js"

The `dev` script passes `--host`, which exposes the dev server on the network rather than only on localhost. For a project whose whole purpose is handing you an image URL to paste somewhere else, that is a deliberate convenience rather than an accident.

The test setup is worth a note. It is the Node built-in test runner with a glob over `test/*.test.js`, not Vitest and not Jest, so the tests run with no extra dependency and no configuration file for the runner. The `vitest.config.ts` style file that most Vite projects carry is absent here, and the top level entries confirm it: there is no test config file beyond the glob in the script.

The runtime dependencies are React and React DOM at 19.2.7, and the dev dependencies are the React type packages, the Vite React plugin at 6.0.2 and Vite itself at 8. On the React 19 line with Vite 8, this is a current dependency set rather than a pinned older one.

There is no linting script and no formatter configuration in the manifest, which is a small inconsistency in an otherwise tidy project, and no CI or deployment configuration is visible in the top level entries beyond the `.github/` directory.

Two hosting options, and the project page is a demo rather than the tool

The README lists two addresses and the distinction between them matters.

The first is the maintainer's own domain, https://icon.yukonga.top/, described as the author's own domain. The second is the GitHub Pages site, https://yukonga.github.io/HQ-ICON/. The README calls the latter the GitHub Page, and the homepage in the repository metadata points at the same address.

Given that the package is private and there is no published build or npm package, the natural reading is that the GitHub Pages deployment is the built application, hosted as a static site, while the custom domain is the maintainer's own deployed instance. Both are listed so that the tool is reachable either way.

That is worth understanding because it affects what you can expect from each. A Pages deployment of a Vite app is a static bundle, so the search requests are made from your browser, and the tool works as long as the API is reachable from wherever you are. The maintainer's own domain is a hosted instance he controls and can update independently of the Pages build.

The documentation itself is thin. There is no separate documentation directory, no changelog and no issue template described in the README beyond the standard links. The parameters table, the two regional paragraphs and the acknowledgements are the entire guide, which is consistent with a project whose complexity is bounded by the API it calls.

The copyright and licence position is clear. The project is MIT licensed with the terms in the LICENSE file at the repository root, and the repository is not archived with the last push on 2026-09-30. There are no GitHub releases attached, so there is no tagged version history to track, and the version 1.1.3 in the manifest is the only version reference available.

Editorial conclusion

Adopt HQ-ICON if you need App Store artwork at a specific size and format without going to the store page by hand, and you are happy with a web tool rather than a library. Do not adopt it as a dependency inside another application, since the repository is a private Vite front end with a test script and no published package, and do not expect it to find apps that are not listed in the region you select. Verify first that the app id you have is listed in the storefront you are querying, since some apps are not on sale in every region, and set the country parameter explicitly rather than relying on the current selection.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. YuKongA/HQ-ICON on GitHub