Guide for when to use Catalog Search vs Location Search

This guide explains the difference between the Catalog search/nearby endpoints and the Location search/nearby endpoints: what they do, how they differ, and when to use each.

Use case

When to use the Catalog Endpoints

Use case	Why Catalog
Building or editing your allowlist	You need to see all matching locations in an area so you can choose which ones to add to your `/allowlist/`. Location Search would only show what’s already allowed.
Discovery and research	You’re exploring what’s available (e.g. “what restaurants exist near this point?”) without being limited by your current config.
Internal tools and admin	Dashboards or tools that need to browse the full catalog, manage geo config, or support allowlist workflows.
Testing or debugging	You want to confirm that data exists for a query or area; Production might return empty because of gating.

Catalog endpoints are meant for reference and configuration, not for high-volume traffic from your end users.

When to use the Location Search/Nearby API

Use case	Why Location Search/Nearby
“Near me” in your app	You only want to show places that are part of your existing allowed list of locations.
Search in your product	User types a query; you only want results that are in your allowlist and within your geo setup.
Map or list of supported locations	You’re displaying only the locations your product supports in that region.
Any consumer-facing search or nearby	You need the full location payload (e.g. photos, review count) and higher throughput.

Location Search/Nearby is for live traffic where every result must respect your allowlist and geofencing.

Response shape

	Catalog	Production
Content	Abbreviated: id, name, address, coordinates, description, overall_rating, urls. For nearby with lat/lon: distance_miles, distance_meters, bearing	Full: Same core fields plus full location details, review count, optional photos (e.g. with `include_photo`), and other fields per your API spec
Photos	No photo objects in the default catalog response	Photos available when requested

Use Catalog endpoints when you only need enough to identify a place and use Location Search/Nearby endpoints when you need full details and assets for your UI.