Icon Search — Font Awesome Free Metadata API

Search the open-source Font Awesome Free icon set by keyword, synonym, alias or category and get back clean, structured records a developer or agent can drop straight into a UI or a design pipeline.

Give it a query (e.g. arrow, user, payment) and it returns one dataset item per matching icon with:

• name, label, unicode, html_entity (e.g. )
• styles and the free/pro split: free_styles, pro_only_styles, is_free, is_pro_only
• categories (from Font Awesome's own category metadata)
• search_terms (the icon's synonyms)
• css_classes per style (e.g. fa-solid fa-arrow-left)
• svg_urls — canonical public SVG URLs on jsDelivr for every free style
• canonical_url — the icon's page on fontawesome.com

Optional style filter (solid / regular / brands) and limit (1–200).

Example

Input:

{ "query": "payment", "style": "any", "limit": 5 }

Returns credit-card, cash-register, cart-shopping, money-bill, … each as a full record. Example item:

{
  "name": "credit-card",
  "label": "Credit Card",
  "unicode": "f09d",
  "html_entity": "",
  "styles": ["solid", "regular"],
  "free_styles": ["solid", "regular"],
  "pro_only_styles": [],
  "is_free": true,
  "is_pro_only": false,
  "categories": ["money", "shopping"],
  "css_classes": {
    "solid": "fa-solid fa-credit-card",
    "regular": "fa-regular fa-credit-card"
  },
  "svg_urls": {
    "solid": "https://cdn.jsdelivr.net/gh/FortAwesome/Font-Awesome@6.5.2/svgs/solid/credit-card.svg",
    "regular": "https://cdn.jsdelivr.net/gh/FortAwesome/Font-Awesome@6.5.2/svgs/regular/credit-card.svg"
  },
  "canonical_url": "https://fontawesome.com/icons/credit-card",
  "font_awesome_version": "6.5.2",
  "license": "Icons CC BY 4.0; code/metadata MIT — Font Awesome Free"
}

Pricing

Pay-per-event: one returned icon = one icon-returned event ≈ USD 0.01 (see .actor/pay_per_event.json). No subscription, no minimum.

Data source & license (important)

This actor reads only the public, openly licensed Font Awesome Free metadata at runtime from the official open-source repository, served over public CDNs:

• https://cdn.jsdelivr.net/gh/FortAwesome/Font-Awesome@<version>/metadata/icons.json
• https://cdn.jsdelivr.net/gh/FortAwesome/Font-Awesome@<version>/metadata/categories.yml
• SVG URLs point at the same public repo path.

Font Awesome Free license (https://fontawesome.com/license/free):

• Icons: CC BY 4.0 — attribution required.
• Code & metadata (including icons.json): MIT.
• Fonts: SIL OFL 1.1.

We surface metadata and link to canonical public assets; we do not re-host, relicense, or expose any Pro-only asset. Pro-only styles are reported as flags with no SVG URL. "Font Awesome" is a trademark of Fonticons, Inc.; this is an unofficial, independent utility and is not affiliated with or endorsed by Fonticons, Inc.

No proxies, no login-walled data, no scraping of a hostile surface — only owner-published, openly licensed public metadata.

Run / verify locally (no Apify, no APIFY_TOKEN, no Docker)

The search logic is isolated from the Apify runtime so it runs offline:

python3 scripts/smoke.py            # sample queries: arrow, user, payment
python3 scripts/smoke.py payment    # ad-hoc query
python3 -m unittest discover -s tests -v   # offline unit tests (network-free fixture)

scripts/smoke.py fetches the live public metadata when the network is available and falls back to a small bundled authentic snapshot (fixtures/sample_icons.json) otherwise, so it always demonstrates real matches. The apify dependency is only used inside the Apify runtime (src/main.py).

Commercial ancestry

Reverse-engineers the proven mechanism one_time_digital_asset_freemium_icons (ancestry: Font Awesome) via a license-clean route: instead of re-selling assets, it sells fast, structured search over openly licensed metadata — useful to developers and coding agents building UIs. See foundry/money_artery/plays.jsonl (play-font-awesome).

Status

Minimum executable form is built, smoke-tested and unit-tested locally. Publication to the Apify Store is owner/environment-gated — see EXECUTION_STATUS.md.