--- title: "Search businesses" method: GET path: "/v1/search" tags: ["Discovery"] --- # Search businesses `GET /v1/search` ## Request - Base URL: `https://loppee.com` - URL: `https://loppee.com/v1/search` - Auth: none declared Taxonomy/category discovery requires a current-location proof or handoff, a Sponsored-neutral validated-destination authority that preserves plan-based organic reach, or saved_exact Home. A connected-assistant current-location handoff from the registered Loppee iPhone is organic-only: no Sponsored ordering or labels, click/recommendation attribution, or exposure accounting. Coarse city/state and ZIP are neutral context only and return no local category results, no Sponsored placement, and no impressions. Provider IP, caller coordinates, host metadata, and computer/browser current location are never accepted as connected-assistant current-location authority. Exact and genuine-prefix business-name lookup remains universal and commercially neutral without precise location. Within the three-mile Free reach, category search may include Registry records that retain exact claim_status and disclosure and remain outside published Verified/Listed classes; identity-verified reviewer ratings can order quality within the Registry pool, while payment has no quality influence. Exposure-plan payment changes discovery reach, gallery capacity, and, when Sponsored ordering is active, labeled position-weighted exposure only within the same verification class and verified-review reputation band. It never changes business-profile publication, verification, review authority, reputation, moderation, class ordering, or reputation band. Loppee Jobs is a separate optional paid product; its billing affects job-posting activation only and never business verification or directory ranking. ## Query parameters - `q` string: Free-text search. Category terms auto-route to precise-location-gated discovery; otherwise exact and genuine-prefix business-name lookup is universal and commercially neutral without precise location. - `category` string: Taxonomy category alias or category term. Resolved categories require recognized current-location, validated-destination, or saved_exact authority; coarse context returns no local results. - `intent` 'auto' | 'category' | 'name' | 'search_category' | 'category_search' | 'lookup' | 'lookup_business' | 'business_name': Routing hint: auto (default), category, or name; legacy value aliases remain accepted. - `search_intent` 'auto' | 'category' | 'name' | 'search_category' | 'category_search' | 'lookup' | 'lookup_business' | 'business_name': Deprecated alias of intent; legacy value aliases remain accepted. - `city` string: City context. With state, it can disambiguate a business name but cannot enable local category/recommendation reach, Sponsored placement, or impressions. - `state` string: Two-letter US state or territory code. With city, this is neutral area context for business-name disambiguation; it is not precise local-discovery authority. - `zip` string: 5-digit US ZIP (ZIP+4 accepted). Its ZCTA centroid is neutral area context for business-name disambiguation only; it cannot enable local category/recommendation reach, Sponsored placement, or impressions. - `radius_miles` number: Requested area radius. It never substitutes for recognized current-location, validated-destination, or saved_exact authority. Universal name lookup may use it only as neutral context. - `include_directory_listings` boolean: Include honestly labeled, unverified directory listings for discovery. - `paid_only` boolean: Consumer-directory paid-exposure presentation filter. - `consumer_reach` boolean: Consumer web/mobile directory policy: ignore caller radius_miles and enforce each result's exact plan/branch radius for category and partial/fuzzy name discovery. Literal exact and genuine-prefix entity-name matches remain universal and commercially neutral. Agents should normally omit it. - `location_selection` 'saved' | 'current' | 'destination' | 'provided': The customer's explicit location choice. Current, a user-confirmed validated destination handoff, or Home when reach_precision=exact can authorize local category/recommendation discovery. Provided city/ZIP and coarse Home are neutral area context for business-name disambiguation only. Ask exactly: 'Where should I search? For local categories, use your current location, enter a different service address securely in Loppee, or use Home only when it is marked exact. Another city/ZIP is for area context or business-name lookup only.' Exact and genuine-prefix business-name lookup is exempt. - `saved_location_ref` string: Opaque saved-location reference returned by get_location_options. Required with location_selection=saved. Only kind=saved_exact authorizes local category/recommendation reach; coarse saved kinds remain neutral context. It contains no address, ZIP, latitude, or longitude. - `location_handoff_id` string, uuid: Opaque current-location or validated-destination handoff approved by the consumer. Both authorize plan-based organic local category/recommendation reach and both are Sponsored-neutral: no Sponsored ordering or labels, click/recommendation attribution, or exposure accounting. Current location must come from the registered Loppee iPhone. Requires the same active scoped consumer-agent connection that created it. Do not combine it with lat/lng, ZIP, city, or state; Loppee uses the point privately and never returns an address or coordinates to the agent. - `location_proof_id` string, uuid: Opaque short-lived current-location or validated-destination proof. It may be created by an authenticated Loppee customer or same-origin browser flow; the attested iOS lane remains current-location only. Do not combine it with any other location input; the address and exact point remain private. - `cursor` string: Opaque cursor returned in next_cursor by the previous v3 search page. Omit for the first page. - `limit` integer: Maximum result count from 1 to 50. ## Response `200` SearchResponse - union - unknown - unknown ## Other responses - `400`: For a local category or recommendation lane, current-location, validated-destination, or saved_exact authority is required. Coarse context fails closed with precise_location_required and sponsored_exposure_recorded=false. Exact/genuine-prefix name lookup remains universal. - `403`: The location authority is not bound to the same active scoped consumer-agent key or authenticated customer session, or that authority is no longer active. - `429`: RateLimitError - `default`: ErrorResponse --- [API](https://skmtc.dev/loppee/apis/loppee-business-registry-api-for-external-agents.md) · [All operations](https://skmtc.dev/loppee/apis/loppee-business-registry-api-for-external-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/loppee/apis/loppee-business-registry-api-for-external-agents/revisions/37285f7cddcd?raw)