--- title: "Recommend businesses" method: GET path: "/v1/recommend" tags: ["Discovery"] --- # Recommend businesses `GET /v1/recommend` ## Request - Base URL: `https://loppee.com` - URL: `https://loppee.com/v1/recommend` - Auth: none declared Local category recommendations require 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 location context cannot return local recommendations, activate Sponsored placement, or record impressions. Exact and genuine-prefix entity-name lookup remains universal and commercially neutral without precise location. Reviewed Registry records may fill category recommendations within the three-mile Free reach while retaining their exact claim-state disclosure and remaining outside published Verified/Listed classes. At most one claim-state-accurately warned fallback is allowed only after all higher-authority pools are empty. In exact/genuine-prefix name recommendations, identity-reviewed Registry records may participate in direct-entity relevance without reach_eligibility; unrated fallback, Sponsored placement, and paid exposure are forbidden. 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 across the published pool. Exact and genuine-prefix name lookup remains universal; category recommendations require precise location authority. - `category` string: Business category or taxonomy term. Local recommendations require recognized current-location, validated-destination, or saved_exact authority. - `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. - `allowed_action` string: Require a published allowed action such as recommend or call_business. - `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. - `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)