@builtbyecho/public-api-finder 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BuiltByEcho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# Public API Finder
+
+Find free/public APIs for agents, prototypes, demos, and integrations.
+
+Powered by the curated [`public-api-lists/public-api-lists`](https://github.com/public-api-lists/public-api-lists) JSON dataset.
+
+## Quick start
+
+```bash
+npx @builtbyecho/public-api-finder "weather forecast" --no-auth --https
+npx @builtbyecho/public-api-finder "crypto prices" --category Cryptocurrency --limit 5
+npx @builtbyecho/public-api-finder "jobs" --json
+```
+
+## Why
+
+Agents often waste time wandering the web for APIs. This gives them a small, predictable first stop: search a curated list, filter by auth/HTTPS/CORS, then verify the chosen API docs before coding.
+
+## Skill
+
+The package includes an agent skill at:
+
+```text
+skills/public-api-finder/SKILL.md
+```
+
+The skill tells agents to prefer the CLI first, then live-check docs/endpoints before building.
+
+## CLI options
+
+```text
+--category <name>  Filter by category substring
+--no-auth          Only APIs with Auth = No
+--https            Only HTTPS APIs
+--cors <value>     Filter by CORS: Yes, No, Unknown
+--limit <n>        Max results
+--json             Emit JSON
+--refresh          Refresh cache
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@builtbyecho/public-api-finder",
+  "version": "0.1.0",
+  "description": "Find free/public APIs for agents and prototypes.",
+  "type": "module",
+  "bin": {
+    "public-api-finder": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "public-api",
+    "apis",
+    "cli",
+    "skills"
+  ],
+  "author": "BuiltByEcho",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BuiltByEcho/public-api-finder.git"
+  }
+}

package/skills/public-api-finder/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: public-api-finder
+description: Find and evaluate free/public APIs for projects, demos, agents, prototypes, data enrichment, examples, integrations, or research. Use the simple public-api-finder CLI to choose APIs by category, auth requirements, HTTPS/CORS support, and practical fit before writing integration code.
+---
+
+# Public API Finder
+
+Use this skill when a task needs a public API candidate. The agent-friendly path is the CLI first, then live-check docs/endpoints before coding.
+
+## Quick command
+
+```bash
+npx @builtbyecho/public-api-finder "weather forecast" --no-auth --https
+npx @builtbyecho/public-api-finder "crypto prices" --category Cryptocurrency --limit 5
+npx @builtbyecho/public-api-finder "jobs" --json
+```
+
+If npm is unavailable, use the bundled fallback script:
+
+```bash
+python3 skills/public-api-finder/scripts/search_public_apis.py "weather forecast" --no-auth --https
+```
+
+Resolve the fallback script path relative to this `SKILL.md`.
+
+## Output to user
+
+Recommend 2-5 APIs. Include:
+
+- API name and URL
+- What it is good for
+- Auth requirement
+- HTTPS/CORS notes
+- One caveat to verify: rate limits, pricing, docs freshness, uptime, or terms
+- Minimal example request only after checking docs/live endpoint
+
+## Heuristics
+
+Prefer APIs that are HTTPS-enabled, no-auth or simple API key, CORS `Yes` for frontend demos, well documented, and narrowly suited to the task.
+
+The curated list is not a production-readiness guarantee. Always verify before building around an API.

package/skills/public-api-finder/scripts/search_public_apis.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Search public-api-lists for agent-friendly API candidates."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+SOURCE_URL = "https://public-api-lists.github.io/public-api-lists/api/all.json"
+CACHE_PATH = Path(os.environ.get("PUBLIC_API_FINDER_CACHE", "~/.cache/public-api-finder/all.json")).expanduser()
+CACHE_TTL_SECONDS = 24 * 60 * 60
+
+
+def load_data(refresh: bool = False) -> list[dict[str, Any]]:
+    CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    fresh = CACHE_PATH.exists() and (time.time() - CACHE_PATH.stat().st_mtime) < CACHE_TTL_SECONDS
+    if refresh or not fresh:
+        with urllib.request.urlopen(SOURCE_URL, timeout=20) as res:
+            data = json.load(res)
+        CACHE_PATH.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    else:
+        data = json.loads(CACHE_PATH.read_text(encoding="utf-8"))
+    return data.get("entries", [])
+
+
+def tokens(text: str) -> set[str]:
+    return {t for t in re.findall(r"[a-z0-9]+", text.lower()) if len(t) > 1}
+
+
+def score(entry: dict[str, Any], query_tokens: set[str]) -> int:
+    hay = " ".join(str(entry.get(k, "")) for k in ("name", "description", "category"))
+    hay_tokens = tokens(hay)
+    name_tokens = tokens(str(entry.get("name", "")))
+    category_tokens = tokens(str(entry.get("category", "")))
+    desc_tokens = tokens(str(entry.get("description", "")))
+    return (
+        5 * len(query_tokens & name_tokens)
+        + 4 * len(query_tokens & category_tokens)
+        + 2 * len(query_tokens & desc_tokens)
+        + len(query_tokens & hay_tokens)
+    )
+
+
+def filter_entries(entries: list[dict[str, Any]], args: argparse.Namespace) -> list[dict[str, Any]]:
+    q_tokens = tokens(args.query or "")
+    out = []
+    for e in entries:
+        if args.category and args.category.lower() not in str(e.get("category", "")).lower():
+            continue
+        if args.no_auth and str(e.get("auth", "")).lower() != "no":
+            continue
+        if args.https and not e.get("https"):
+            continue
+        if args.cors and args.cors.lower() != str(e.get("cors", "")).lower():
+            continue
+        s = score(e, q_tokens) if q_tokens else 1
+        if q_tokens and s == 0:
+            continue
+        item = dict(e)
+        item["score"] = s
+        out.append(item)
+    return sorted(out, key=lambda x: (-x["score"], str(x.get("category", "")), str(x.get("name", ""))))[: args.limit]
+
+
+def markdown(rows: list[dict[str, Any]]) -> str:
+    if not rows:
+        return "No matching public APIs found. Try broader terms or remove filters."
+    lines = []
+    for i, e in enumerate(rows, 1):
+        auth = e.get("auth", "Unknown")
+        https = "yes" if e.get("https") else "no"
+        cors = e.get("cors", "Unknown")
+        lines.append(
+            f"{i}. **{e.get('name')}** ({e.get('category')}) — {e.get('description')}\n"
+            f"   - URL: {e.get('url')}\n"
+            f"   - Auth: `{auth}` · HTTPS: {https} · CORS: {cors} · score: {e.get('score')}"
+        )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Search public-api-lists for API candidates")
+    ap.add_argument("query", nargs="?", default="", help="Search terms, e.g. 'weather forecast' or 'crypto prices'")
+    ap.add_argument("--category", help="Filter by category substring")
+    ap.add_argument("--no-auth", action="store_true", help="Only APIs that list Auth as No")
+    ap.add_argument("--https", action="store_true", help="Only HTTPS APIs")
+    ap.add_argument("--cors", choices=["Yes", "No", "Unknown"], help="Filter by CORS value")
+    ap.add_argument("--limit", type=int, default=8, help="Maximum results")
+    ap.add_argument("--json", action="store_true", help="Emit JSON")
+    ap.add_argument("--refresh", action="store_true", help="Refresh local cache")
+    args = ap.parse_args()
+
+    try:
+        rows = filter_entries(load_data(args.refresh), args)
+    except Exception as exc:
+        print(f"public-api-finder: failed to load API list: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        print(markdown(rows))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/cli.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const SOURCE_URL = 'https://public-api-lists.github.io/public-api-lists/api/all.json';
+const CACHE_PATH = join(homedir(), '.cache', 'public-api-finder', 'all.json');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+function usage() {
+  console.log(`public-api-finder — find public APIs for agents and prototypes
+
+Usage:
+  public-api-finder <query> [options]
+
+Options:
+  --category <name>  Filter by category substring
+  --no-auth          Only APIs with Auth = No
+  --https            Only HTTPS APIs
+  --cors <value>     Filter by CORS: Yes, No, Unknown
+  --limit <n>        Max results (default: 8)
+  --json             Emit JSON
+  --refresh          Refresh cache
+  -h, --help         Show help
+
+Examples:
+  public-api-finder "weather forecast" --no-auth --https
+  public-api-finder "crypto prices" --category Cryptocurrency --limit 5
+  public-api-finder "jobs" --json
+`);
+}
+
+function parseArgs(argv) {
+  const args = { query: '', limit: 8, json: false, refresh: false };
+  const parts = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') args.help = true;
+    else if (a === '--no-auth') args.noAuth = true;
+    else if (a === '--https') args.https = true;
+    else if (a === '--json') args.json = true;
+    else if (a === '--refresh') args.refresh = true;
+    else if (a === '--category') args.category = argv[++i] || '';
+    else if (a === '--cors') args.cors = argv[++i] || '';
+    else if (a === '--limit') args.limit = Number(argv[++i] || 8);
+    else parts.push(a);
+  }
+  args.query = parts.join(' ').trim();
+  return args;
+}
+
+function tokenSet(text) {
+  return new Set(String(text).toLowerCase().match(/[a-z0-9]+/g)?.filter(t => t.length > 1) || []);
+}
+
+function intersectionCount(a, b) {
+  let n = 0;
+  for (const x of a) if (b.has(x)) n++;
+  return n;
+}
+
+function score(entry, queryTokens) {
+  const name = tokenSet(entry.name);
+  const category = tokenSet(entry.category);
+  const desc = tokenSet(entry.description);
+  const all = new Set([...name, ...category, ...desc]);
+  return 5 * intersectionCount(queryTokens, name)
+    + 4 * intersectionCount(queryTokens, category)
+    + 2 * intersectionCount(queryTokens, desc)
+    + intersectionCount(queryTokens, all);
+}
+
+async function cacheIsFresh() {
+  try {
+    const s = await stat(CACHE_PATH);
+    return Date.now() - s.mtimeMs < CACHE_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+async function loadData(refresh = false) {
+  if (!refresh && await cacheIsFresh()) {
+    return JSON.parse(await readFile(CACHE_PATH, 'utf8')).entries || [];
+  }
+  const res = await fetch(SOURCE_URL);
+  if (!res.ok) throw new Error(`failed to fetch API list: HTTP ${res.status}`);
+  const data = await res.json();
+  await mkdir(dirname(CACHE_PATH), { recursive: true });
+  await writeFile(CACHE_PATH, JSON.stringify(data, null, 2));
+  return data.entries || [];
+}
+
+function filterEntries(entries, args) {
+  const q = tokenSet(args.query);
+  return entries.flatMap(e => {
+    if (args.category && !String(e.category || '').toLowerCase().includes(args.category.toLowerCase())) return [];
+    if (args.noAuth && String(e.auth || '').toLowerCase() !== 'no') return [];
+    if (args.https && !e.https) return [];
+    if (args.cors && String(e.cors || '').toLowerCase() !== args.cors.toLowerCase()) return [];
+    const s = q.size ? score(e, q) : 1;
+    if (q.size && s === 0) return [];
+    return [{ ...e, score: s }];
+  }).sort((a, b) => b.score - a.score || String(a.category).localeCompare(String(b.category)) || String(a.name).localeCompare(String(b.name))).slice(0, args.limit);
+}
+
+function printMarkdown(rows) {
+  if (!rows.length) {
+    console.log('No matching public APIs found. Try broader terms or remove filters.');
+    return;
+  }
+  rows.forEach((e, i) => {
+    console.log(`${i + 1}. **${e.name}** (${e.category}) — ${e.description}`);
+    console.log(`   - URL: ${e.url}`);
+    console.log(`   - Auth: \`${e.auth}\` · HTTPS: ${e.https ? 'yes' : 'no'} · CORS: ${e.cors} · score: ${e.score}`);
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.query) {
+    usage();
+    return args.help ? 0 : 1;
+  }
+  const rows = filterEntries(await loadData(args.refresh), args);
+  if (args.json) console.log(JSON.stringify(rows, null, 2));
+  else printMarkdown(rows);
+  return 0;
+}
+
+main().then(code => process.exitCode = code).catch(err => {
+  console.error(`public-api-finder: ${err.message}`);
+  process.exitCode = 1;
+});