How AXVO finds, scores, and ranks free healthcare

A transparent, academic-quality account of the data sources, scoring models, deduplication logic, and quality safeguards that power the AXVO clinic finder. No black boxes.

Data Sources & Collection Pipeline

AXVO aggregates healthcare facility data from four independent sources, ordered by authority and verification level. Each source covers a distinct population of clinics that the others miss.

1.1 HRSA Health Center Finder (Primary)

The Health Resources and Services Administration (HRSA) maintains a database of all federally qualified health centers (FQHCs) — the approximately 1,400 HRSA-designated grantees operating 14,000+ delivery sites across the United States. FQHCs are legally required under Section 330 of the Public Health Service Act to provide care on a sliding-fee scale regardless of a patient's ability to pay, and cannot turn away any patient for inability to pay.

We query the HRSA API sequentially against three known endpoint variants (the HRSA API has changed endpoints across versions) and parse all known response shapes:

• findahealthcenter.hrsa.gov/api/v1/healthcenter/FindHealthCenters
• findahealthcenter.hrsa.gov/api/v1.0/FindHealthCenters
• findahealthcenter.hrsa.gov/api/HealthCenterFinder/FindHealthCenters

HRSA results are assigned an affordability score of 95/100 and are always ranked before supplementary sources. Response caching is set to 1 hour (3,600 seconds) via Next.js ISR.

1.2 NAFC Member Clinics (Secondary)

The National Association of Free & Charitable Clinics (NAFC) represents 1,200+ volunteer-run free clinics that are not federally qualified — meaning they do not appear in HRSA's database. These clinics charge $0 to patients and operate on donations and volunteer labor. They fill a critical gap for patients in rural areas and underserved urban neighborhoods.

AXVO maintains a curated static database of 130+ verified NAFC member clinics compiled from the NAFC member directory, individual clinic websites, and Google Places verification. Each entry is manually reviewed for accuracy. This database is stored in lib/nafc-clinics.ts and queried in-memory using a Haversine distance calculation — zero latency, zero API dependency.

NAFC clinics receive an affordability score of 90/100. They are labeled "FREE CLINIC" in the UI to distinguish them from FQHCs.

1.3 OpenStreetMap Overpass API (Supplementary)

OpenStreetMap (OSM) provides crowd-sourced location data for healthcare facilities. We query the Overpass API for nodes and ways tagged with amenity=clinic, amenity=hospital, healthcare=*, and social_facility=outreach within a bounding box around the user's location.

OSM data quality varies significantly. We apply the affordability scoring model (Section 2) to each result and only include OSM clinics with a score ≥ 55/100 in the merged output, ensuring low-confidence results are excluded. OSM results are always ranked after HRSA and NAFC. Response caching is 2 hours (7,200 seconds).

1.4 Google Places API (Optional Tertiary)

When a GOOGLE_PLACES_API_KEY environment variable is configured, AXVO runs a tertiary search against the Google Places Nearby Search API using keywords "free clinic" and "community health center". Results are filtered to affordability score ≥ 45/100 before inclusion. This source is strictly optional and not required for core functionality.

1.5 State Health Department Directories

For searches in California, Texas, New York, Florida, and Illinois — the five states with the largest uninsured populations — AXVO queries public clinic directories exposed via data.gov and state open-data portals. These are scraped at query time with results cached for 24 hours and filtered by proximity and affordability score.

Affordability Scoring Model

Every non-HRSA clinic is scored on a 0–100 affordability scale. This score determines whether a clinic appears in results, its sort order relative to other clinics, and the label shown in the UI (LIKELY FREE / LOW COST / STANDARD).

The model begins with a base score of 40 and applies additive and subtractive adjustments based on signals extracted from the clinic name and OpenStreetMap tags. Each signal is derived from published research on how clinic naming conventions correlate with care affordability.

2.1 Name-Based Signals (additive)

2.2 Tag-Based Signals (additive)

2.3 Exclusion Signals (subtractive)

2.4 Label Thresholds

Deduplication & Merge Logic

The same physical clinic often appears in multiple data sources under slightly different names. Without deduplication, a user would see the same clinic listed 3–4 times with slightly different data, degrading trust and usability.

AXVO uses a name fingerprinting approach: each clinic name is normalized to its first 12 lowercase alphanumeric characters, forming a fingerprint. A hash set of seen fingerprints is maintained as sources are merged in priority order. The first occurrence of each fingerprint wins.

When HRSA returns a clinic, any NAFC or OSM entry with a matching fingerprint is suppressed — HRSA's data (phone, address, hours) is treated as authoritative. This ensures that federally-verified data is never overwritten by crowd-sourced approximations.

Specialty Classification

AXVO classifies clinics into six specialty categories used by the search filter: Primary care, Mental health, Dental, Women's health, Pediatrics, and Vision. Classification uses a name-and-tag pattern matching approach:

When a specialty filter is applied and returns zero results, AXVO falls back to the full unfiltered list and surfaces a warning: "No exact [specialty] match — showing nearby clinics." This prevents users from seeing an empty results page when only a few clinics in the area don't match the pattern.

For HRSA clinics, specialty data is also derived from the SiteServiceDescription field in the API response where available, supplementing name-based inference.

Geographic Resolution

User location input (ZIP code, city name, or address) is geocoded using the Nominatim API (OpenStreetMap's free geocoder, US-constrained). Nominatim returns a latitude/longitude centroid, which is used for:

• HRSA API queries (ZIP code parameter)
• Haversine distance calculation for NAFC and OSM results
• Overpass API bounding box construction (±1.2× radius in degrees)
• Map panel centering

The Haversine formula is used for all distance calculations. It computes the great-circle distance between two points on a sphere (Earth radius = 3,958.8 miles):

The user's ZIP code is also persisted to localStorage under the key axvo_zip, enabling pre-fill across the Pathways, Calendar, and Search pages without requiring an account.

Data Freshness & Quality Assurance

6.1 ISR Caching Tiers

6.2 Automated Freshness Monitoring

Three Vercel Cron jobs run automatically to maintain data quality:

• Clinic Freshness Bot (weekly, Sunday 2 AM UTC): Re-validates HRSA availability for the 20 most-searched ZIP codes. Flags any ZIP codes where HRSA returns zero results when historical data suggests there should be clinics nearby.
• Broken Link Checker (biweekly, Monday 3 AM UTC): Sends HTTP HEAD requests to all external URLs in the platform (program links, NAFC clinic websites, external references). Flags any returning 4xx/5xx or timing out.
• Weekly Impact Digest (weekly, Monday 8 AM UTC): Compiles aggregate usage metrics (searches, outcomes logged, new users) into an email digest sent via Resend.

Privacy & Data Ethics

Limitations & Known Gaps

We document known limitations transparently. Users and researchers should be aware of the following:

• HRSA API reliability: The HRSA Find a Health Center API has experienced intermittent outages and endpoint changes. AXVO tries three known endpoint variants but cannot guarantee availability. In HRSA outage conditions, the platform falls back to NAFC and OSM data.
• Rural gaps: In counties with no HRSA grantee, FQHC look-alike, or NAFC member clinic within 25 miles, AXVO returns OSM results that may include non-free clinics. The affordability score attempts to filter these, but false positives are possible.
• Hours and availability: Clinic hours change frequently. While the platform displays hours when available from HRSA or OSM tags, these may be stale. Users should always call ahead to confirm hours and appointment availability.
• NAFC completeness: The static NAFC database includes 130+ manually verified entries out of 1,200+ NAFC members. Clinics not in this database may still exist in users' areas. The NAFC member locator at nafc.org is recommended as a supplementary resource.
• Name-based affordability scoring: The scoring model is heuristic-based. A clinic named "Eastside Medical Center" with no affordability signals would score 40/100 (STANDARD) even if it is FQHC-affiliated. Scores should be interpreted as affordability probability indicators, not guarantees.
• Specialty classification accuracy: Specialty detection is name-pattern-based only. A community health center that offers dental care but does not include "dental" in its name will not surface in dental-filtered searches.

Citing AXVO

If you use AXVO data or methodology in academic work, presentations, or grant applications, please cite as follows:

Questions about methodology? Reach out via the feedback form or contact the AXVO research team. We welcome collaboration with public health researchers, academic institutions, and policy organizations studying healthcare access disparities.