🔭 Supplier Scout
Find suppliers of goods and services, including the ones that are not online, by typing what you need in your own words.
Live map search · real order cost · fair ratings · trust from referrals · human review · optional Claude agent.
▶ Live demo · How it works · Cómo funciona (español) · 🇪🇸 Resumen en español · Playbook: suppliers that are not online · Countries and languages
The problem
Finding a new supplier usually means a web search, a spreadsheet and a few phone calls. Three things go wrong:
- The best suppliers are often not on the web. Small workshops, family businesses and distributors who sell by phone or WhatsApp have no website. A colleague knows them, a current supplier buys from them, or they are in a public registry or on a community map. Web search never shows them.
- The cheapest list price is rarely the cheapest order. Pack sizes, minimum orders, tax, shipping and payment terms change the total. A $2,100 box with a 1,000-unit minimum and 10-day delivery loses to a $2,600 box delivered in 2 days.
- Star ratings mislead. A 5.0 from 2 reviews beats a 4.7 from 300, and a supplier with no online reviews looks worse than one with bad reviews.
The full walkthrough, from the live map search to how the ranking decides, is in How it works (español).
What it does
- Understands what you need, in your own words, and finds real businesses on the map. Type air conditioning maintenance, plumber, fire extinguisher refill or cardboard boxes plus a neighbourhood and a city. Rules (no AI) turn the request into OpenStreetMap tags and words found in business names, for 27 trades and services and 12 purchase categories in four languages, with regional words (gasfitero, refaccionaria, tlapalería, gomería, borracharia, desentupidora), and the app says what it understood. Places are identified the way buyers name them: a whole town or city (Barranquilla, San Gil), a neighbourhood, or the browser's location; towns that share a name are told apart by region and offered as alternatives, and a place typed with the wrong country is found anyway. The demo searches OpenStreetMap, the community map where many shops and workshops with no website are listed, reports how many have no website, links every result to its map entry, and opens the same search in Google Maps with one click (an official link: no key, no scraping).
- Searches by location. Distance from your delivery point, a search radius, and suppliers that deliver are kept even when they are far.
- No quantities to find options. Purchasing starts by gathering several options and negotiates amounts later, so the search ranks by quoted unit price (when there is one), distance, ratings, trust and speed. Quote requests for a service ask for the price of the job, what it includes and the response time. Once quotes arrive, the Quotes tab turns each one into the real cost of an order: whole packs, the minimum order, tax, shipping, your currency (at a rate you set) and, optionally, the value of paying later.
- Rates fairly. A Bayesian average of online reviews and your own team's reviews. No reviews means "unknown", not "bad".
- Shows them on a real map, with driving times. An OpenStreetMap map (no library, tiles only for the area in view) with the search radius and numbered markers that jump to each card; in a live search, one OSRM request adds the approximate driving time and road distance to every business. Each card has Call, its address and opening hours, its map entry and a Google Maps search.
- Follows how purchasing actually decides. Filters for with phone and no website and a nearest order; a shortlist (My list) that keeps the suppliers to contact with their status (to contact, contacted, quoted, chosen, discarded), shows progress towards the usual three quotes, sends one personalised quote request to everyone still pending over WhatsApp or email (a one-to-many request, as in Thomasnet, over the channel the region uses), links each supplier to its country's official registry and tax portals (RUES and DIAN, SAT, SUNAT, SII, ARCA, SRI, Receita Federal), and downloads a comparison table () for Excel or Sheets with price, lead time, payment terms, warranty and notes. Quote requests can include the documents needed to register a supplier (in Colombia: RUT, Chamber of Commerce certificate, bank certificate, legal representative's ID).
Finding suppliers that are not online
This is the core of the project. The full guide is in the playbook.
| Channel | How Supplier Scout helps |
|---|
| Referrals from current suppliers and colleagues | Drafts the "who do you buy this from?" message; records who recommended whom; counts only independent referrals toward trust |
| Public registries (procurement, chambers of commerce) | SECOP II connector for Colombia; an OCDS connector for every government that publishes open contracting data; any Socrata open-data portal; CSV import for any other registry. The app lists each country's procurement portal and business registry |
| Community maps | Live OpenStreetMap search in the web app and a connector in the CLI, for any country, reporting how many results have no website; a one-click Google Maps search for the businesses OSM does not have |
| Trade districts and fairs | CSV import that recognises columns by name in Spanish, English, Portuguese and French |
| Business cards, flyers, WhatsApp | Rule-based parser: name, tax ID with check digit, phones, emails, handles, address, prices, pack size, minimum order, lead time, payment terms |
| Verification | Tax-ID check digits, verification levels (contacted → formal → visited → bought from), human review queue |
How the ranking works
| Factor | What it measures | When data is missing |
|---|
| Price | Quoted unit price with tax relative to the cheapest option; in the Quotes tab, the total cost of an order (packs, minimum, tax, shipping, currency, payment term) | Neutral + "ask for a quote" |
| Rating | Bayesian blend: a neutral prior worth 5 reviews, online reviews (capped at 100), team reviews ×3 | Neutral |
| Distance | Inside your radius; suppliers that deliver keep a floor | Neutral |
| Trust | Verification level + independent referrals (self and same-group referrals ignored, mutual ones count half) | Lowest level |
| Speed | Lead time; a hard warning if it misses your deadline | Neutral |
Weights are presets (balanced, cheapest, most reliable, nearest, urgent) or sliders.
Countries and languages
Built in Colombia, meant for Latin America, usable anywhere. The full table is in docs/countries.md.
- 23 country profiles + a generic one: the 17 Spanish-speaking countries of Latin America from Mexico to Argentina (Cuba uses the generic profile), plus Puerto Rico, Brazil, Spain, Portugal, France and the US. Each one knows its currency, its sales tax name and default rate (IVA, IGV, ITBIS, ITBMS, ISV, IVU, TVA), its tax ID, its phone habits and where formal suppliers are listed (procurement portal, business registry, data-protection law).
- Tax-ID check digits in 13 countries, including Brazil's alphanumeric CNPJ (from July 2026). Where no public check-digit rule exists (Mexico's RFC, Venezuela's RIF, most of Central America), the ID is checked for format and the app says "format only" instead of "valid".
- How suppliers actually write: Argentina's "15" mobiles, Mexico's old "044", RD$, quetzales, colones, guaraníes, "+ IGV", "com impostos", "HT", an arroba (12.5 kg in Colombia, 15 kg in Brazil), tlapalería or ferragens, and addresses by landmark ("100 varas al sur").
- Four languages: the web app, the explanation of every ranking, the quote and referral requests (which name the local tax: "¿incluye IGV?") and the agent. The app follows the browser's language.
- Sample data for Bogotá, Mexico City and São Paulo.
Design decisions
- Missing data is neutral, never zero. This is what lets an offline supplier with no reviews and no quote yet compete with a web shop, while still showing what to ask for.
- Precision over recall for duplicates. Same tax ID, phone, email or corporate domain merges automatically; a similar name alone always goes to a person. Two different valid tax IDs are never merged, even with a shared phone.
- The agent cannot invent suppliers. The output file contains only suppliers a tool returned. Whatever the model writes is used for the summary and the drafts, not as data.
- One logic, three front ends.
src/core is plain JavaScript with no dependencies. The browser demo, the CLI and the agent run the same code, and the tests cover it.
- Country-agnostic by configuration. A country is one profile: currency, default sales tax, tax-ID rules, phone habits and local weights. Adding one touches no other file. Local details are respected: a "libra" in a Colombian market is 500 g, and a regional unit always asks for confirmation.
- Honest validation. A tax ID is "valid" only when a check digit proves it; otherwise the app says "format only". A label shared by several countries ("RUC" is used in five) switches country only on a verified check digit, never on a guess.
- No AI where rules are enough. Card and WhatsApp parsing is rule-based, runs offline and is predictable. The model is used only where it adds something: planning a search from a plain-language request.
The AI agent
agent/ uses the Claude API (official @anthropic-ai/sdk, model claude-opus-5-5 by default) with seven read-only tools: find_coordinates, search_my_database, search_map, search_public_registry (Colombia), search_google_places (only if you set a key), rank_candidates and draft_messages.
- It only reads and drafts. There is no tool to send messages, write files or browse arbitrary pages. You review and send.
- Data minimisation. Phone numbers and emails never go to the model; WhatsApp links for the drafts are filled in locally. Suppliers who refused consent for their personal data are ranked locally but never described to the model.
- Cost control. At most 12 steps per run, effort
medium, prompt caching, and token usage printed at the end.
- Safety. Tool results are treated as data, not instructions (a business name on a map could contain text meant to manipulate the model). If a safety classifier declines a request, the API's server-side fallback retries on its recommended model (
fallbacks: "default").
--dry-run runs the same tools in a fixed order without AI or a key, to try it or compare.- Language:
--lang es|en|pt|fr; by default, the language of the country (--country BR answers in Portuguese).
Security
| Risk | Mitigation |
|---|
| AI invents suppliers, prices or reviews | Candidates come only from tool results; the loop is tested with a scripted model that tries to invent one |
| Prompt injection through third-party data (names, notes) | Tools are read-only; no send or write tools; the system prompt marks tool output as data; a person sends every message |
| Personal data sent to the AI provider | Tool results strip phones and emails (tested) |
| API keys leaking | Keys only in environment variables (.env is git-ignored, .env.example is empty); the Places key goes in a header, never the URL (tested) |
| Query injection (Overpass QL, SoQL) | User text is reduced to letters and digits before building map queries; SoQL string literals are escaped (tested) |
Malicious import file (XSS, javascript: links, huge files) | One sanitising gate for all external data (also applied to what the browser saved, since storage is shared by every page on the same GitHub Pages domain); http(s) links only; 2 MB limit; the page renders with textContent only |
| Huge or hostile inputs (availability) | Capture text capped at 5,000 characters and tested against regex backtracking; imports capped at 2,000 suppliers; duplicate search and ranking tested to stay fast at those limits; connector responses capped at 5 MB while streaming |
| Spreadsheet formula injection in the CSV export | Cells starting with =, +, -, @ are exported as text (tested) |
| Demo page | Strict CSP: scripts, styles and fonts (IBM Plex, self-hosted, SIL Open Font License) come from the site itself; connect-src allows only Nominatim, Overpass and the OSRM routing server, used only when you press Search the map, and img-src only OpenStreetMap's tiles (tested). Marker colours are set through the CSSOM because inline style attributes are blocked. No cookies or trackers. Map results go through the same sanitising gate as any import; the shortlist and recent places read back from storage are checked the same way |
| Personal data of sole traders (Colombia: Law 1581 of 2012; LGPD in Brazil and similar laws across the region) | Consent checkbox on capture that names the selected country's law, warning in the ranking when consent was refused, never sent to the AI agent when refused, data stays in the browser unless exported. The OCDS connector imports the business, never the contact person's name (tested) |
Architecture
flowchart LR
subgraph S[Where suppliers come from]
MAP[OpenStreetMap]
REG[Public registries<br/>SECOP · OCDS · Socrata portals]
GP[Google Places<br/>optional key]
CSV[CSV<br/>fairs · chambers · sheets]
CARD[Cards · flyers · WhatsApp]
REF[Referrals]
end
MAP --> CON[Connectors · Node]
REG --> CON
GP --> CON
CSV --> CON
CARD --> PAR[Capture parser<br/>rules · offline]
REF --> PAR
CON --> GATE[(Common format<br/>sanitised)]
PAR --> REV{Human review}
GATE --> DUP{Duplicates<br/>confidence tiers}
DUP -->|exact · high · medium| DB[(Supplier list)]
DUP -->|low · conflict| REV
REV --> DB
DB --> RANK[Ranking<br/>order cost · fair rating<br/>distance · trust · speed]
RANK --> WEB[Web app]
RANK --> AG[Claude agent]
AG -.->|drafts only| YOU[You send quote<br/>and referral requests]
Project structure
src/core/ shared logic, no dependencies (browser + Node)
services.js what the buyer typed -> trades, categories, map tags and name words (rules, ES/EN/PT/FR)
osm.js OpenStreetMap query and parsing, place disambiguation and search radius, Google Maps search link
shortlist.js the buyer's shortlist: statuses, three-quote progress, comparison table (CSV)
countries.js 23 country profiles: currency, tax, tax-ID check digits, phone habits, registries
capture.js business card / flyer / WhatsApp text -> draft supplier
quotes.js units, packs, minimum order, tax, shipping, FX, payment terms
reviews.js Bayesian rating blend
trust.js verification levels and referral counting
dedupe.js duplicate detection with confidence tiers, merging
score.js explainable ranking
csv.js · schema.js import/export and the sanitising gate
messages.js explanations (ES / EN / PT / FR) · outreach.js quote & referral drafts
src/connectors/ OpenStreetMap, Socrata/SECOP, OCDS, Google Places, Nominatim (Node)
src/data/ fictional demo data (Bogotá, Mexico City and São Paulo)
cli/scout.js connectors, CSV import, merge and rank from the terminal (args.js: shared parser)
agent/ Claude agent: tools, loop, system prompt, CLI
demo/ the web app (GitHub Pages): app.js, live.js (the only file that uses the network), map.js (OSM tiles + markers,
no library), i18n.js (ES/EN/PT/FR texts), self-hosted IBM Plex fonts
tests/ 179 tests: core, regional formats, connectors against API-shaped fixtures,
CLI, agent loop with a scripted model, demo security guards
docs/ how it works (ES/EN), screenshots, the offline playbook and the country coverage table
Run it
Requires Node 22+.
npm test # the whole suite, no network and no API key needed
Web app: open the live demo, or serve the repository locally (for example npx http-server .) and open /demo/.
Connectors (no AI): each command writes a JSON file you import in the web app (tab Data).
npm install
npm run scout -- osm --category packaging --lat 4.6782 --lng -74.1411 --radius 3000 --out data/map.json
npm run scout -- registry --preset secop-co --describe # show the dataset's columns and how they were mapped
npm run scout -- registry --preset secop-co --q "carton corrugado" --city Bogota --out data/secop.json
npm run scout -- registry --domain https://data.example.gov --dataset abcd-1234 --country XX --q "..." # any Socrata portal
npm run scout -- ocds --file releases.json --country PY --q "carton" --out data/ocds.json # any OCDS publisher (or --url https://...)
npm run scout -- csv --file exhibitors.csv --country CO --out data/fair.json
npm run scout -- merge data/map.json data/secop.json data/fair.json --out data/all.json
npm run scout -- rank --db data/all.json --category packaging --qty 500 --lat 4.6782 --lng -74.1411 --radius 12 --days 7
Agent:
cp .env.example .env # put your ANTHROPIC_API_KEY in .env (never in code)
node --env-file=.env agent/cli.js "Necesito 500 cajas de cartón corrugado cerca de Fontibón, Bogotá, en 7 días" \
--db data/all.json --out data/result.json
# Without AI or a key: the same tools in a fixed order
npm run agent -- --dry-run --db data/all.json --category packaging --qty 500 --lat 4.6782 --lng -74.1411 --days 7
data/ is git-ignored so your real supplier lists never end up in the repository.
What is tested, and what is not
Being explicit, because this matters more than the feature list:
- Tested (179 automated tests in CI): all core logic; every country profile; check digits with fictional numbers that pass and fail; cards and WhatsApp messages written the way suppliers write in Mexico, the Dominican Republic, Brazil, Ecuador, Chile, Peru, Costa Rica and France; the connectors against fictional fixtures shaped like each API's documented responses (OCDS included); the CLI end to end; the agent loop against a scripted stand-in for the Claude API (tool calls, parallel results, errors, refusals, step limit, append-only history, no invented suppliers, no phones sent to the model); that every interface text exists in the four languages; how typed requests are understood in four languages; place disambiguation and the city-wide radius; the shortlist and its CSV; the live map search, driving times and retries with simulated OpenStreetMap and OSRM responses (geocoding, results, errors, size and time limits); the demo's CSP and rendering guards; speed at the import limits. The web app was checked in Chromium in the four languages, in light and dark mode, on desktop and on a 390 px phone viewport.
- Checked against official sources, not against live systems: the check-digit algorithms were compared with examples published by each tax authority (those real numbers are not kept in the repository). Tax rates, portal names and law names are as of 2026 and are editable defaults, not tax or legal advice.
- Checked against the live services (November 2026): a manual GitHub Actions workflow (
live-check.yml) runs the web app's own search code against the real Nominatim, Overpass and OSRM for 12 buyer searches in Colombia, Peru, Mexico and Brazil, checks every listed business on the OpenStreetMap API, and uses the page in Chromium. Results: 67 of 67 businesses checked in three runs exist with the same name; searches with good map coverage found 16-37 real businesses (hardware stores in Barranquilla and Coyoacán, stationers in Chapinero, garages in Pinheiros); the map tiles, driving times, shortlist and quote request worked in the real browser with no console or security-policy error. The check also found real problems, now fixed: the public Overpass server took about 30 s to answer from GitHub's servers (hence the Nominatim fallback), searches took 13-20 s (now 3-13 s), place labels were long, and municipalities came back as "county".
- Not run against live services: the CLI's SECOP, OCDS and Google Places connectors and the Claude agent; their request formats follow each service's documentation.
- Known limits: results depend on what volunteers have mapped: trades such as plumbers, locksmiths, pest control or fire-extinguisher refills often return few or no businesses (0 in San Gil, Cali, Medellín and Miraflores in the live check), and phone numbers are on roughly 1 in 10 map results, which is why every search also opens in Google Maps; the Nominatim fallback returns at most 40 businesses per type; GitHub Pages cannot send security headers, so the CSP is a tag and cannot forbid framing (the page has no sensitive actions to hijack); driving times come from the OSRM demo server, ignore traffic and fall back to straight-line distance when it is unavailable; tax rates are editable defaults and import duties are not included; the capture parser handles common formats and anything unusual needs a manual fix, which is why every capture goes to review.
Roadmap
- Supplier self-registration: a QR code at a fair booth linking to a Google Form, imported through the same CSV path (an Apps Script adapter, as in Supplier Radar).
- Photo of a business card: OCR (a local model such as Qwen, or Claude vision) feeding the same rule-based parser.
- WhatsApp inbox to review queue with an n8n flow.
- Run the agent with a local model for zero API cost.
- Landed cost
- An agent tool for OCDS publishers; check digits for Mexico's RFC homoclave and Venezuela's RIF.
About
Built by Sergio García, an International Business graduate (diploma pending) based in Bogotá who likes turning repetitive work into automated systems. I don't come from engineering: I learn by building, using generative AI as a pair programmer. Supplier Scout is an independent project built with Claude Code; the design choices (neutral scoring for missing data, human review, drafts instead of automatic messages) come from what I saw of how purchasing actually works.
Companion project: Supplier Radar keeps track of the suppliers you already have; Supplier Scout finds new ones.
Portfolio · LinkedIn · [email protected]
🇪🇸 Resumen en español
Supplier Scout sirve para encontrar proveedores nuevos de productos y servicios, incluidos los que no aparecen en internet, escribiendo lo que necesitas con tus palabras.
- Entiende lo que necesitas y busca negocios reales en el mapa: escribes mantenimiento de aires acondicionados, plomero, recarga de extintores o cajas de cartón, más la ciudad, el pueblo o el barrio (o usas tu ubicación). Si hay varios pueblos con el mismo nombre, te muestra cuál eligió y te ofrece los otros. Unas reglas (sin IA) lo convierten en etiquetas de OpenStreetMap y palabras del nombre del negocio, y la app te dice qué entendió. Busca en OpenStreetMap, donde aparecen muchos talleres y locales sin página web, dice cuántos no tienen web, enlaza cada resultado a su ficha y con un clic abre la misma búsqueda en Google Maps (enlace oficial: sin claves y sin copiar datos).
- Busca por ubicación: distancia desde tu punto de entrega, radio de búsqueda y proveedores que hacen envíos.
- Sin cantidades para buscar: en compras primero se buscan opciones y la cantidad se negocia después. El ranking usa el precio por unidad cotizado (si lo hay), la distancia, las reseñas, la confianza y la rapidez. Cuando ya tienes cotizaciones, la pestaña Cotizaciones calcula el costo real del pedido: paquetes completos, compra mínima, IVA, envío, moneda y el valor de pagar a plazo.
- Mapa real y lista corta: los resultados aparecen en un mapa de OpenStreetMap con el tiempo aproximado en carro a cada negocio. Mi lista guarda los que vas a contactar, su estado y el avance hacia las tres cotizaciones que se suelen pedir, y descarga el cuadro comparativo para Excel o Sheets. La solicitud de cotización puede pedir los documentos para inscribir al proveedor (RUT, Cámara de Comercio, certificación bancaria, cédula).
- Reseñas justas: un 5.0 con 2 reseñas no le gana a un 4.7 con 300, y "sin reseñas" cuenta como neutro, no como malo. Las reseñas de tu equipo pesan más.
- Proveedores fuera de internet: conectores a OpenStreetMap (cualquier país) y a SECOP II (Colombia), importación de CSV (ferias, cámaras de comercio), lector de tarjetas, volantes y mensajes de WhatsApp (funciona sin IA y sin internet) y una red de recomendaciones donde solo cuentan las independientes.
- Revisión humana: lo capturado y los posibles duplicados pasan a una cola de revisión. Las solicitudes de cotización y de recomendaciones se redactan para que tú las envíes.
- Agente de IA opcional (Claude): le escribes "necesito 500 cajas de cartón cerca de Fontibón en 7 días" y busca en tu lista, en el mapa y en SECOP, clasifica y redacta los mensajes. No puede inventar proveedores ni enviar nada, y nunca ve teléfonos ni correos.
- Pensado para América Latina, útil en cualquier país: 23 perfiles (los países hispanohablantes de la región, salvo Cuba que usa el genérico, más Puerto Rico, Brasil, España, Portugal, Francia y EE. UU.) más uno genérico. Cada uno conoce su moneda, su impuesto (IVA, IGV, ITBIS, ITBMS, ISV...), su ID tributario (con dígito de verificación en 13 países, incluido el CNPJ alfanumérico de Brasil), cómo se escriben los teléfonos, las unidades locales (arroba, quintal, libra) y dónde buscar proveedores formales (portal de compras públicas, registro de empresas y ley de datos). Hay conector para los datos abiertos de compras públicas en formato OCDS.
Los datos de ejemplo de la demo son ficticios (dominios .example, teléfonos en rangos sin asignar, IDs tributarios generados); los de la búsqueda en el mapa son reales. Honestidad: la búsqueda en el mapa, los conectores y el agente están probados con respuestas simuladas; todavía no se han ejecutado contra los servicios reales porque el entorno de desarrollo no tenía acceso a internet. Ver la demo en vivo · Cómo funciona · Guía para encontrar proveedores fuera de internet.
License
MIT
