{
  "openapi": "3.1.0",
  "info": {
    "title": "AssistAnt pro directory",
    "version": "1.3.0",
    "description": "Free, read-only API over a nationwide U.S. directory of 39 kinds of local service businesses (appliance repair businesses; dryer vent and duct cleaning businesses; used and scratch-and-dent appliance sellers; HVAC companies; plumbers; electricians; roofing companies; landscaping, lawn care and tree service companies; cleaning companies; pest control companies; locksmiths; painters; garage door companies; handymen; pool and spa companies; restoration companies; concrete, masonry and paving contractors; fence companies; gutter companies; septic companies; chimney sweeps and chimney repair companies; junk removal companies; home inspectors; flooring companies; window and door companies; home security companies; remodeling contractors; insulation contractors; solar installers; well drilling companies; towing companies; auto repair shops; collision repair and auto glass shops; diesel and truck repair shops; motorcycle, marine and small engine repair shops; welding and metal fabrication shops; machine shops; computer, phone repair and IT service businesses; excavation, crane and heavy equipment companies; trucking companies). Verified businesses (registration and insurance checked by AssistAnt, with the date) come first, then distance. Placement cannot be bought and AssistAnt never sells a person's information. Rules: https://assistant247.net/how-we-verify. Also available as an MCP server at https://assistant247.net/mcp.",
    "contact": {
      "url": "https://assistant247.net/find"
    },
    "license": {
      "name": "Listings include Overture Maps Foundation data (CDLA-Permissive-2.0)",
      "url": "https://cdla.dev/permissive-2-0/"
    }
  },
  "servers": [
    {
      "url": "https://assistant247.net"
    }
  ],
  "paths": {
    "/api/pros": {
      "get": {
        "operationId": "findPros",
        "summary": "Find local service businesses (39 trades: appliance repair, HVAC, plumbers, electricians, auto repair, towing, welders and more) near a U.S. ZIP code or coordinates",
        "description": "Returns businesses ordered verified-first, then by match and distance. If a problem is given, free repair guides that match come back first (help before a sales call). Never a dead end: for appliance services, when nothing is within 40 miles a nationwide video-diagnosis option is returned; for every other trade, an honest note says how far the closest listed business is. brand, appliance and problem apply to appliance services only. An unknown service is a 400 that lists the valid ones.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$"
            },
            "description": "5-digit U.S. ZIP code (or give lat and lon)"
          },
          {
            "name": "lat",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "service",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "appliance_repair",
                "dryer_vent_cleaning",
                "used_appliances",
                "appliance_store",
                "duct_cleaning",
                "hvac",
                "plumbing",
                "electrical",
                "roofing",
                "landscaping",
                "cleaning",
                "pest_control",
                "locksmith",
                "painting",
                "garage_door",
                "handyman",
                "pool_spa",
                "restoration",
                "concrete_masonry",
                "fence",
                "gutters",
                "septic",
                "chimney",
                "junk_removal",
                "home_inspection",
                "flooring",
                "windows_doors",
                "security_systems",
                "remodeling",
                "insulation",
                "solar",
                "well_drilling",
                "towing",
                "auto_repair",
                "collision",
                "diesel_truck",
                "power_sports",
                "welding",
                "machine_shop",
                "computer_repair",
                "heavy_equipment",
                "trucking",
                "aquarium"
              ],
              "default": "appliance_repair"
            },
            "description": "What the person needs. appliance_repair = Appliance repair; dryer_vent_cleaning = Dryer vent cleaning; used_appliances = Used & scratch-and-dent appliances; appliance_store = Appliance store; duct_cleaning = Air duct cleaning; hvac = Heating & air conditioning (HVAC); plumbing = Plumbing; electrical = Electrical; roofing = Roofing; landscaping = Landscaping, lawn, tree & irrigation; cleaning = Cleaning (home, office, carpet, pressure washing); pest_control = Pest control; locksmith = Locksmith; painting = Painting; garage_door = Garage door repair; handyman = Handyman; pool_spa = Pool & spa service; restoration = Water, fire & mold restoration; concrete_masonry = Concrete, masonry & paving; fence = Fencing; gutters = Gutters; septic = Septic service; chimney = Chimney sweep & repair; junk_removal = Junk removal; home_inspection = Home inspection; flooring = Flooring; windows_doors = Windows & doors; security_systems = Home security systems; remodeling = Remodeling; insulation = Insulation; solar = Solar installation; well_drilling = Well drilling & pumps; towing = Towing & roadside; auto_repair = Auto repair; collision = Collision & auto glass; diesel_truck = Diesel & truck repair; power_sports = Motorcycle, marine & small engine; welding = Welding & fabrication; machine_shop = Machine shops & CNC; computer_repair = Computer & phone repair / IT; heavy_equipment = Excavation & heavy equipment; trucking = Trucking; aquarium = Aquarium service & fish."
          },
          {
            "name": "brand",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "e.g. samsung, lg, whirlpool, ge, sub-zero, viking, speed-queen"
          },
          {
            "name": "appliance",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "refrigerator",
                "freezer",
                "ice_maker",
                "washer",
                "dryer",
                "dishwasher",
                "oven_range",
                "microwave",
                "wine_cooler",
                "disposal"
              ]
            }
          },
          {
            "name": "problem",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "What is wrong, in plain words, including any error code"
          },
          {
            "name": "segment",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "residential",
                "commercial"
              ],
              "default": "residential"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Missing or unknown location"
          }
        }
      }
    },
    "/pros/{slug}": {
      "get": {
        "operationId": "getProProfile",
        "summary": "One business's full listing",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Last part of the profile URL"
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such listing"
          },
          "410": {
            "description": "Removed at the business's request"
          }
        }
      }
    },
    "/{service}/{state}/{town}": {
      "get": {
        "operationId": "getTownSummary",
        "summary": "Counts and the listed-first businesses within 25 miles of a town",
        "parameters": [
          {
            "name": "service",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "appliance-repair",
                "dryer-vent-cleaning",
                "used-appliances",
                "hvac",
                "plumbers",
                "electricians",
                "roofers",
                "landscapers",
                "cleaning-services",
                "pest-control",
                "locksmiths",
                "painters",
                "garage-door-repair",
                "handyman",
                "pool-service",
                "restoration",
                "concrete-contractors",
                "fence-contractors",
                "gutter-services",
                "septic-services",
                "chimney-services",
                "junk-removal",
                "home-inspectors",
                "flooring",
                "windows-and-doors",
                "home-security",
                "remodeling-contractors",
                "insulation-contractors",
                "solar-installers",
                "well-drilling",
                "towing",
                "auto-repair",
                "collision-repair",
                "truck-repair",
                "motorcycle-marine-repair",
                "welders",
                "machine-shops",
                "computer-repair",
                "excavation",
                "trucking"
              ]
            },
            "description": "Town-page path of the service: appliance-repair (appliance_repair), dryer-vent-cleaning (dryer_vent_cleaning), used-appliances (used_appliances), hvac (hvac), plumbers (plumbing), electricians (electrical), roofers (roofing), landscapers (landscaping), cleaning-services (cleaning), pest-control (pest_control), locksmiths (locksmith), painters (painting), garage-door-repair (garage_door), handyman (handyman), pool-service (pool_spa), restoration (restoration), concrete-contractors (concrete_masonry), fence-contractors (fence), gutter-services (gutters), septic-services (septic), chimney-services (chimney), junk-removal (junk_removal), home-inspectors (home_inspection), flooring (flooring), windows-and-doors (windows_doors), home-security (security_systems), remodeling-contractors (remodeling), insulation-contractors (insulation), solar-installers (solar), well-drilling (well_drilling), towing (towing), auto-repair (auto_repair), collision-repair (collision), truck-repair (diesel_truck), motorcycle-marine-repair (power_sports), welders (welding), machine-shops (machine_shop), computer-repair (computer_repair), excavation (heavy_equipment), trucking (trucking)."
          },
          {
            "name": "state",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Two-letter state, lowercase (la)"
          },
          {
            "name": "town",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Town slug (covington, new-orleans, saint-louis)"
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Town summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No page for that town yet"
          }
        }
      }
    },
    "/appliances/{brand}/{appliance}": {
      "get": {
        "operationId": "getApplianceKnowledge",
        "summary": "What technicians actually found on a brand + appliance (from real repair records)",
        "description": "Counts from TN Appliance Exchange repair records (what the technician found on diagnosed jobs). Not a reliability ranking. Also /appliances/{appliance}?format=json and /appliances?format=json.",
        "parameters": [
          {
            "name": "brand",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "samsung, lg, whirlpool, ge, frigidaire, maytag, kenmore, hisense"
          },
          {
            "name": "appliance",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "refrigerator",
                "washer",
                "dryer",
                "dishwasher",
                "oven-range"
              ]
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Findings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Not enough records for that brand and appliance"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "free_help_first": {
            "type": "object",
            "description": "Matching free repair guides, shown before any business"
          },
          "no_pro_nearby": {
            "type": "object"
          },
          "privacy": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pro"
            }
          },
          "ranking": {
            "type": "string"
          },
          "how_we_verify": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Pro": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "brands_named": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "appliances_named": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "trust": {
            "type": "object",
            "properties": {
              "tier": {
                "type": "string",
                "enum": [
                  "listed",
                  "verified_public",
                  "verified_data"
                ]
              },
              "label": {
                "type": "string"
              },
              "claimed_by_business": {
                "type": "boolean"
              },
              "verified_on": {
                "type": "string",
                "format": "date"
              }
            }
          },
          "bookable_online": {
            "type": "boolean"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "website": {
            "type": [
              "string",
              "null"
            ]
          },
          "distance_miles": {
            "type": "number"
          },
          "profile": {
            "type": "string",
            "format": "uri"
          },
          "trust_card": {
            "type": "string",
            "format": "uri",
            "description": "AssistAnt Trust Card (JSON): every fact we verified about this business, how and when, plus what is not verified yet."
          }
        }
      }
    }
  }
}