{"openapi":"3.0.3","info":{"title":"Feed America API","description":"API for finding food assistance resources across all 50 US states, DC, Puerto Rico, and US territories. 321K+ locations including food pantries, food banks, soup kitchens, mobile pantries, community fridges, SNAP retailers, WIC offices, school/summer meal sites, and FQHC community health centers.","version":"2.1.0","contact":{"email":"info@feedam.org","url":"https://feedam.org"}},"servers":[{"url":"https://feedam-api.emperormew.workers.dev","description":"Production"}],"paths":{"/api/llm-search":{"get":{"summary":"Natural-language search for AI assistants. Accepts free-form English queries and extracts location + mode + urgency automatically. Designed for OpenAI Custom GPTs, Claude Tools, Perplexity custom actions. CORS-enabled for browser AI clients.","operationId":"llmSearch","parameters":[{"name":"q","in":"query","required":true,"description":"Free-form English (or Spanish) query about food assistance. Examples: \"I need food today in Houston\", \"free food pantry near 77065\", \"WIC clinic near 90001\", \"How do I apply for SNAP in Texas\".","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results with structured intent + natural-language answer","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"The original input query"},"intent":{"type":"object","description":"Extracted intent: location, mode, urgency, action","properties":{"location":{"type":"string","description":"5-digit ZIP or \"City, ST\""},"state":{"type":"string","description":"2-letter US state code"},"mode":{"type":"string","enum":["free","snap","wic","school","summer"]},"urgent":{"type":"boolean"},"intent":{"type":"string","enum":["find","apply"]}}},"answer":{"type":"string","description":"Natural-language answer the AI can return verbatim or rephrase"},"action":{"type":"string","description":"What the response represents: search_results | apply_snap | apply_wic | need_location"},"result_count":{"type":"integer"},"total_available":{"type":"integer"},"resources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string"},"address":{"type":"string"},"phone":{"type":"string","nullable":true},"distance_miles":{"type":"number","nullable":true},"open_status":{"type":"string","enum":["open","closed","closes_soon","opens_soon","unknown"]},"feedam_detail_url":{"type":"string","format":"uri"}}}},"related_links":{"type":"object","description":"Useful follow-up URLs the AI can offer"},"attribution":{"type":"string"}}}}}}}}},"/api/resources/search":{"get":{"summary":"Search resources by ZIP or city. Params: zip, mode (free|snap|school|summer|wic|health), type, radius, limit. Returns relevance_score, hours_status, total_available, and auto-expands the radius when zero results within 50mi."}},"/api/resources/nearby":{"get":{"summary":"Search by lat/lng directly. Params: lat, lng, mode, radius, limit."}},"/api/resources/urgent":{"get":{"summary":"Currently-open free food resources. Params: zip or lat/lng, radius."}},"/api/resources/counts":{"get":{"summary":"Per-mode result counts within 150mi of a ZIP. Use before searching so you can show users \"Free Food (47), SNAP (183), Health Centers (2)\" etc. Returns {free, snap, school, summer, wic, health}. 300s cache."}},"/api/resources/{id}":{"get":{"summary":"Single resource with hours_status."}},"/api/resources/{id}/status":{"get":{"summary":"Phone validation, hours status, verification confidence."}},"/api/resources/types":{"get":{"summary":"All resource categories with counts."}},"/api/resources/bulk":{"get":{"summary":"Paginated export (JSON/CSV). Params: page, limit (max 1000), format, state, type."}},"/api/autocomplete":{"get":{"summary":"City name autocomplete. Param: q (min 2 chars)."}},"/api/stats":{"get":{"summary":"Live database statistics."}},"/api/stats/quality":{"get":{"summary":"Verification rates and freshness metrics."}},"/api/feedback":{"post":{"summary":"Submit feedback (helpful|wrong_info|closed|other)."}},"/api/partner/find":{"get":{"summary":"Find your listing. Params: name, zip."}},"/api/partner/edit":{"post":{"summary":"Submit edit for review. Body: resource_id, changes, submitted_by."}},"/api/sms":{"post":{"summary":"Twilio-compatible SMS webhook. Send ZIP to get 3 nearest resources."}},"/api/widget":{"get":{"summary":"Embeddable HTML food finder widget. Param: zip."}},"/api/analytics/dashboard":{"get":{"summary":"Search analytics: daily counts, top ZIPs, zero-result searches."}},"/api/snap/calculate":{"post":{"summary":"SNAP benefit calculator (2024-2025 USDA tables)."}},"/api/health":{"get":{"summary":"Health check."}},"/api/health/deep":{"get":{"summary":"Deep health check with DB connectivity test."}},"/llms.txt":{"get":{"summary":"LLM-friendly API summary with live counts, endpoint list, and data sources."}},"/llms-full.txt":{"get":{"summary":"Full-data LLM text export: per-category records with address and phone, up to 200 per category."}},"/sitemap.xml":{"get":{"summary":"Dynamic sitemap including state + long-tail city food-pantry landing pages."}},"/hsds/v3/":{"get":{"summary":"HSDS 3.0 Open Referral feed landing page (HTML). See also /hsds/v3/datapackage.json for the Frictionless Data descriptor. 10 entity endpoints: organizations, services, locations, service_at_location, phones, addresses, schedules, languages, taxonomy_terms, attributes."}},"/hsds/v3/datapackage.json":{"get":{"summary":"HSDS 3.0 data package descriptor (Frictionless Data format) listing all resource URLs, schemas, and license info."}},"/hsds/v3/organizations":{"get":{"summary":"HSDS Organization entities. Params: page, per_page (max 1000), format (json|csv). ~143k records."}},"/hsds/v3/services":{"get":{"summary":"HSDS Service entities — one per active resource. ~200k records."}},"/hsds/v3/locations":{"get":{"summary":"HSDS Location entities — physical location with lat/lng. ~200k records."}},"/hsds/v3/service_at_location":{"get":{"summary":"HSDS ServiceAtLocation joins. ~200k records."}},"/hsds/v3/phones":{"get":{"summary":"HSDS Phone entities. ~147k records with phone number."}},"/hsds/v3/addresses":{"get":{"summary":"HSDS Address entities. ~200k records."}},"/hsds/v3/schedules":{"get":{"summary":"HSDS Schedule entities with iCal RRULE fields (freq, byday, opens_at, closes_at). ~128k records with hours."}},"/hsds/v3/languages":{"get":{"summary":"HSDS Language entities per service. ~124k records."}},"/hsds/v3/taxonomy_terms":{"get":{"summary":"HSDS TaxonomyTerm entities — 11 food-assistance category terms."}},"/hsds/v3/attributes":{"get":{"summary":"HSDS Attribute entities mapping services to taxonomy terms. One per active resource."}},"/api/pantry/search":{"get":{"summary":"Find claimable pantries for an operator. Params: zip (required, 5-digit), q (optional partial name). Returns up to 25 within 5mi."}},"/api/pantry/claim":{"post":{"summary":"Mint a claim token for a pantry. Body: {resource_id, operator_email, operator_phone, operator_name}. Returns {claim_token, dashboard_url}. Idempotent per (resource_id, email)."}},"/api/pantry/manage/{token}":{"get":{"summary":"Operator dashboard data: claim + resource + recent statuses + current live status. Auth: token in URL path."}},"/api/pantry/status":{"post":{"summary":"Push a live status update. Body: {claim_token, status, notes, inventory}. status ∈ [open_today, closed_today, running_late, low_stock, out_of_stock, other]. Inventory: {produce, dairy, canned, protein, baby, water, bread, other} × {plenty, low, out}. 24h TTL."}},"/api/pantry/{id}/status":{"get":{"summary":"Public read — current (non-expired) live status for a resource. 60s cache. Returns null if no active report."}},"/api/disasters/active":{"get":{"summary":"Currently-active FEMA declarations in a ZIP or state. Params: zip (5-digit) OR state (2-letter). Returns declarations + has_dsnap_likely flag."}},"/api/disasters/current":{"get":{"summary":"All currently-open FEMA declarations nationally. No filter. 5-min cache."}},"/api/submissions":{"post":{"summary":"Public crowdsourced pantry submission. Body: {name, address, city, state, zip, resource_type, phone?, website?, hours_text?, services_offered?, requirements_text?, submitter_email?, submitter_name?, submitter_relationship?}. Validates input, dedups by name+zip (409 on duplicate), rate-limits 5/hour per IP. Writes to resources table with is_active=0, verification_status=pending until admin reviews."}},"/api/embed/pantry/{id}.json":{"get":{"summary":"Single-pantry data for partner mobile apps + custom dashboards. Returns name, address, hours_status, phone, badges + embed/detail/directions URLs."}},"/api/embed/catalog.json":{"get":{"summary":"Comprehensive catalog of all Feed America embeddable surfaces (search widget, pantry card, badges, OG cards, JSON APIs, HSDS feed, WordPress plugin, MCP server). 9 items."}},"/atlas.json":{"get":{"summary":"State-by-state hunger atlas snapshot. National totals + per-state counts (food_pantries, food_banks, soup_kitchens, mobile_pantries, wic_clinics, school_meal_sites, summer_meal_sites, fqhc_health_centers, snap_retailers, partner_verified). 1h cache. CC BY 4.0."}},"/api/leaderboard.json":{"get":{"summary":"State-by-state ranking of partner-verified pantries. National totals + ranked array. 10-min cache. CC BY 4.0."}},"/about.json":{"get":{"summary":"Machine-readable About page: organization identity, coverage, data sources, contact, verification, sister entities, disambiguation, products, machine-readable endpoints. v1.0 stable schema."}},"/donate.json":{"get":{"summary":"Machine-readable donation metadata: organization, mailing address, 10 donation channels (online/mail/DAF/stock/crypto/employer/wire/QCD/bequest/recurring), sister entities, disambiguation. v1.0."}},"/snapshot.json":{"get":{"summary":"Single-pull comprehensive Feed America snapshot. Aggregates org + coverage totals + top 10 states by partner-verified + top 10 cities by pantry density + 14 discovery URLs + 9 quick-action URL templates. Saves 5-6 round-trips."}},"/press/feed.json":{"get":{"summary":"JSON Feed (jsonfeed.org/version/1.1) of Feed America press releases. Subscribers: journalists, dev tools that prefer JSON over RSS."}},"/press/feed.atom":{"get":{"summary":"Atom feed of Feed America press releases. Subscribers: news aggregators, RSS readers."}},"/.well-known/security.txt":{"get":{"summary":"RFC 9116 security contact info for vulnerability researchers. Auto-discovered by responsible-disclosure tooling."}},"/security":{"get":{"summary":"Security policy + responsible-disclosure program HTML page. Pairs with /.well-known/security.txt."}},"/atlas/{state}.json":{"get":{"summary":"Per-state hunger atlas JSON snapshot. State, coverage (food_pantry_class subtotal + 5 federal-program counts + SNAP retailers), verification, geographic, top_cities_by_pantry_count, related_surfaces (8 URLs), org. Returns 404 for unknown 2-letter state code."}},"/api/v1/health.json":{"get":{"summary":"Comprehensive public health endpoint. Returns service status, table row counts, verification breakdown, data freshness distribution, coverage totals, discovery URLs. 60s cache for monitoring services."}},"/api/v1/data-quality.json":{"get":{"summary":"Comprehensive data-quality QA report. Field completeness % per pantry-class field (phone, website, hours, address, geocode, services, etc.), verification mix (partner_verified vs verified vs unverified), 30/90/180/365-day freshness distribution, top 20 data sources, deduplication stats, methodology pointer. 30-min cache."}},"/api/feed/news.atom":{"get":{"summary":"Combined Atom firehose: press releases + active FEMA disaster declarations + platform milestones. Subscribers: journalists, RSS aggregators, content-monitoring services, AI clients. 30-min cache. CC BY 4.0."}},"/changelog":{"get":{"summary":"Public platform-updates timeline with NewsArticle JSON-LD per entry. For donors / journalists / partners / AI agents tracking what is new at Feed America."}},"/sponsors":{"get":{"summary":"Corporate giving + matching-gift program landing for CSR officers + ERG leaders. Lists 8+ matching-gift platforms (Benevity, YourCause, etc.) where Feed America is searchable by EIN, plus 4-tier sponsorship pyramid ($25K-$250K+)."}},"/story-pitches":{"get":{"summary":"10 ready-to-write hunger journalism story angles with hooks, citation URLs, suggested experts, follow-up sources. Each angle has a stable anchor URL."}},"/calendar":{"get":{"summary":"Federal food-assistance program calendar with 12 Event JSON-LD entries (SNAP issuance, school year, SFSP, WIC recert, TEFAP, CSFP, FMNP/SFMNP, D-SNAP, IRS deadline, SNAP COLA, WIC food list)."}},"/glossary":{"get":{"summary":"25-term food-assistance acronym dictionary with DefinedTermSet JSON-LD: SNAP, EBT, WIC, TEFAP, CSFP, NSLP, SBP, SFSP, CEP, D-SNAP, FQHC, FNS, FDPIR, FPL, FRAC, HSDS, SDOH, etc."}},"/research":{"get":{"summary":"Academic + journalist data-access landing with Dataset JSON-LD. CC BY 4.0 license; citation guide; 4 dataset distribution formats."}},"/feeds":{"get":{"summary":"Consolidated subscription landing — 13 subscribable feeds catalogued in 5 sections (news firehose, statistical snapshots, org metadata, open data, AI/LLM discovery)."}},"/atlas/{state}":{"get":{"summary":"Per-state Hunger Atlas HTML page with state-by-state stats, top cities by pantry count, federal program context links, citation block. Dataset + BreadcrumbList JSON-LD."}},"/press/{state}":{"get":{"summary":"Per-state press release in journalism format (FOR IMMEDIATE RELEASE / dateline / headline / lede / Sharika Parkes pull-quote / About boilerplate / press contact). NewsArticle JSON-LD."}},"/disasters/{state}":{"get":{"summary":"Per-state FEMA disaster surfacing with active declarations, D-SNAP eligibility, nearest food assistance. Refreshes from active_disasters table (OpenFEMA-sourced, 6h sync)."}},"/embed/catalog":{"get":{"summary":"Embed catalog HTML page — 9 embeddable Feed America surfaces grouped by audience."}},"/embed/pantry/{id}":{"get":{"summary":"Per-pantry live-status iframe widget. Compact 420×380 card with hours_status badge, address, phone, [Get directions] + [Full details] CTAs. CSP frame-ancestors *. postMessage auto-resize. ?theme=dark for dark mode."}},"/partner/leaderboard":{"get":{"summary":"Public partner-verified pantry leaderboard ranked by state. ItemList JSON-LD with top-20."}},"/badges":{"get":{"summary":"Verified Badge program info page."}},"/badge/{id}.svg":{"get":{"summary":"Per-resource Verified Badge SVG (240×60). \"VERIFIED ON\" if partner_verified, \"LISTED ON\" otherwise. CORS-open for cross-origin embed."}},"/badge/{id}":{"get":{"summary":"Per-resource Verified Badge embed-code landing page with copy-paste HTML snippet."}},"/og/resource/{id}":{"get":{"summary":"Per-resource Open Graph card SVG (1200×630). Used as og:image / twitter:image on /resource/{id} pages."}},"/og/atlas/{state}":{"get":{"summary":"Per-state hunger atlas OG card SVG (1200×630). \"FEED AMERICA · ATLAS · <STATE>\" kicker."}},"/og/press/{state}":{"get":{"summary":"Per-state press-release OG card SVG (1200×630). \"FEED AMERICA · PRESS RELEASE · <STATE>\" kicker."}},"/es/atlas":{"get":{"summary":"Spanish Hunger Atlas national hub. Same Dataset JSON-LD as English /atlas with inLanguage=es-US."}},"/es/atlas/{state}":{"get":{"summary":"Spanish per-state hunger atlas. Reciprocal hreflang chain with /atlas/{state}."}},"/es/glossary":{"get":{"summary":"Spanish 25-term food-assistance acronym dictionary. DefinedTermSet with inLanguage=es-US."}},"/es/calendar":{"get":{"summary":"Spanish federal food-assistance program calendar. 12 Event entries with inLanguage=es-US."}},"/es/disasters/{state}":{"get":{"summary":"Spanish per-state FEMA disaster surfacing. GovernmentService JSON-LD with inLanguage=es-US."}}}}