Skip to main content

Place Search API Guide

This guide explains how to use the Vibemap Place Search API to find and filter venues, restaurants, and other locations.

Quick Start​

The base search endpoint is /search/places/ and supports various parameters for searching and filtering places.

Basic Search Example​

GET /search/places/?search=coffee shop

Search Parameters​

Full-Text Search​

Parameter: search

Search across multiple fields including name, description, address, categories, tags, and vibes.

Features:

  • Fuzzy matching - Automatically corrects typos (e.g., "cenntenial" matches "centennial")
  • Partial matching - Finds results even with incomplete words
  • Smart query logic - Short queries (< 10 characters) use OR logic for flexibility, longer queries use AND logic for precision
  • Multi-field search - Searches name, description, address, categories, neighborhood, city, tags, and vibes simultaneously

Examples:

?search=coffee                    # Finds coffee shops
?search=italian restaurant        # Finds Italian restaurants
?search=downtown bars             # Finds bars in downtown area
?search=live music venue          # Searches descriptions and tags

Search Suggestions​

Parameters: name_suggest, name_suggest_context

Get auto-complete suggestions as users type.

name_suggest:

?name_suggest=star                # Returns: "Starbucks", "Star Bar", "Starlight Lounge"...

name_suggest_context: (location-aware suggestions)

?name_suggest_context=cafe&location__geo_distance=5km__37.7749,-122.4194
# Returns cafes within 5km of coordinates

Filter Parameters​

Location Filters​

Filter places by geographic location using coordinates.

Distance Filter​

Parameter: location__geo_distance

Find places within a certain distance from a point.

Format: {distance}__{latitude},{longitude}

Examples:

?location__geo_distance=5km__37.7749,-122.4194          # Within 5km of San Francisco
?location__geo_distance=1mi__40.7128,-74.0060           # Within 1 mile of NYC
?location__geo_distance=500m__51.5074,-0.1278           # Within 500 meters of London

Distance units: km (kilometers), mi (miles), m (meters)

Bounding Box Filter​

Parameter: location__geo_bounding_box

Find places within a rectangular area (useful for map viewport searches).

Format: {top_left_lat},{top_left_lon}__{bottom_right_lat},{bottom_right_lon}

Example:

?location__geo_bounding_box=37.8,-122.5__37.7,-122.3
# Places in a box around San Francisco

Polygon Filter​

Parameter: location__geo_polygon

Find places within a custom polygon shape.

Format: {lat1},{lon1}__{lat2},{lon2}__{lat3},{lon3}...

Example:

?location__geo_polygon=37.8,-122.4__37.7,-122.5__37.6,-122.3__37.8,-122.4
# Places within custom boundary

Category Filters​

Parameters: categories, category, categories.raw

Filter by venue category (restaurant, bar, museum, etc.).

Available lookups:

  • Exact match: ?categories=restaurant
  • Multiple categories (OR): ?categories__in=restaurant,bar,cafe
  • Exclude categories: ?categories__exclude=fast-food
  • Prefix match: ?categories__prefix=rest
  • Wildcard: ?categories__wildcard=*food*

Examples:

?categories=restaurant                                   # Only restaurants
?categories__in=bar,brewery,winery                      # Any of these types
?category=museum                                         # Singular form works too
?categories__exclude=chain                              # Exclude chains
?categories__prefix=coffee                              # Matches coffee-shop, coffeehouse, etc.

Editorial Categories​

Parameters: editorial_categories, editorial_categories.raw

Filter by curated editorial categories (special collections or themes).

Examples:

?editorial_categories=best-brunch-spots
?editorial_categories__in=date-night,romantic
?editorial_categories__exclude=tourist-trap

Tags​

Parameters: tags, tags.raw

Filter by user-generated or content tags.

Examples:

?tags=outdoor-seating                                    # Has outdoor seating
?tags__in=dog-friendly,patio,rooftop                    # Any of these tags
?tags__wildcard=*vegan*                                  # Contains "vegan"

Vibes​

Parameters: vibes, vibes.raw

Filter by subjective atmosphere characteristics (trendy, cozy, upscale, etc.).

Examples:

?vibes=cozy                                              # Cozy atmosphere
?vibes__in=trendy,hip,modern                            # Any of these vibes
?vibes__exclude=loud                                     # Exclude loud venues

Location Text Filters​

Parameters: city, neighborhood, address

Filter by text-based location fields.

Examples:

?city=San Francisco                                      # Specific city
?city.raw=San Francisco                                  # Exact match
?neighborhood=Mission District                           # Specific neighborhood
?address__wildcard=*Market Street*                      # Address contains text

Rating & Quality Filters​

Rating​

Parameter: rating

Filter by place rating (0-5 scale).

Available lookups: __gt, __gte, __lt, __lte, __range

Examples:

?rating__gte=4.0                                         # 4 stars or higher
?rating__range=3.5__5.0                                  # Between 3.5 and 5
?rating__lt=3.0                                          # Less than 3 stars

Combined Score​

Parameter: score_combined

Filter by Vibemap's combined quality score (considers rating, completeness, popularity).

Examples:

?score_combined__gte=80                                  # High quality places
?score_combined__range=60__100                          # Good to excellent

Price Filter​

Parameter: price

Filter by price level (1-4 scale: $ to $$$$).

Examples:

?price=1                                                 # Budget-friendly ($)
?price__lte=2                                            # Budget to moderate ($ - $$)
?price__range=2__3                                       # Moderate to upscale ($$ - $$$)
?price__gte=3                                            # Upscale and fine dining ($$$ - $$$$)

Status Filters​

Boolean filters for place attributes:

ParameterDescriptionExample
is_chainChain/franchise locations?is_chain=false
is_closedPermanently closed?is_closed=false
is_publicPublicly visible?is_public=true
is_flaggedFlagged for review?is_flagged=false
is_duplicateDuplicate entries?is_duplicate=false
user_addedUser-contributed?user_added=true

Examples:

?is_chain=false&is_closed=false                         # Local, open businesses
?user_added=true                                         # Community additions
?is_public=true&is_flagged=false                        # Clean, public listings

Membership Tier​

Parameter: membership_tier

Filter by business membership level.

Examples:

?membership_tier=premium
?membership_tier__in=premium,enterprise
?membership_tier__exclude=free

Other Filters​

Parameter: slug

Filter by URL-friendly identifier.

?slug=blue-bottle-coffee-ferry-building
?slug__prefix=blue-bottle

Parameter: data_source_url

Filter by original data source URL.

?data_source_url__wildcard=*yelp.com*

Sorting & Ordering​

Parameter: ordering

Sort results by various fields. Use - prefix for descending order.

Available sort fields:

  • name - Alphabetical by name
  • location - Geographic distance (requires location filter)
  • vibe_count - Number of vibes assigned
  • aggregate_rating - Average rating
  • score_combined - Combined quality score
  • _score - Search relevance (when using search parameter)

Examples:

?ordering=name                                           # A to Z
?ordering=-aggregate_rating                              # Highest rated first
?ordering=-vibe_count                                    # Most vibed places
?ordering=location&location__geo_distance=5km__37.7749,-122.4194
                                                         # Nearest first
?search=coffee&ordering=-_score                          # Most relevant

Multiple sort fields:

?ordering=-aggregate_rating,name                         # Rating, then alphabetical

Pagination​

Results are paginated with 150 items per page by default.

Parameters:

  • page - Page number (starts at 1)
  • page_size - Items per page (optional, max depends on configuration)

Examples:

?page=1                                                  # First page
?page=2                                                  # Second page
?page_size=50                                            # 50 results per page

More Like This​

Endpoint: /search/places/{id}/more-like-this/

Find similar places based on name, description, and vibes.

Example:

GET /search/places/123/more-like-this/
# Returns places similar to place with ID 123

Response Formats​

Standard JSON​

Default format returns detailed place objects with all attributes.

GeoJSON Format​

Parameter: format=geojson

Returns data in GeoJSON format for mapping libraries.

Example:

?format=geojson&location__geo_distance=5km__37.7749,-122.4194

Returns:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-122.4194, 37.7749]
      },
      "properties": {
        "name": "Place Name",
        "categories": ["restaurant"],
        ...
      }
    }
  ]
}

Common Use Cases​

Find nearby coffee shops​

?search=coffee&location__geo_distance=2mi__37.7749,-122.4194&ordering=location

Highly-rated restaurants with specific vibe​

?categories=restaurant&rating__gte=4.0&vibes=romantic&ordering=-aggregate_rating

Budget-friendly bars with outdoor seating​

?categories=bar&price__lte=2&tags=outdoor-seating&is_closed=false

Local businesses (not chains) in neighborhood​

?neighborhood=Mission District&is_chain=false&is_closed=false&ordering=-score_combined

Search with autocomplete suggestions​

?name_suggest=blue bot
# Returns: "Blue Bottle Coffee", "Blue Bottle - Ferry Building", etc.
?location__geo_bounding_box=37.8,-122.5__37.7,-122.3&format=geojson

Find similar venues​

GET /search/places/456/more-like-this/?ordering=-score_combined

Advanced Combinations​

Premium Italian restaurants near user​

?categories=restaurant
&tags__in=italian,italian-food
&rating__gte=4.0
&price__range=3__4
&location__geo_distance=5mi__40.7128,-74.0060
&ordering=location
&is_closed=false
&is_chain=false

Trendy brunch spots with photos​

?search=brunch
&vibes__in=trendy,hip,instagram-worthy
&rating__gte=3.5
&ordering=-aggregate_rating
&is_closed=false

User-contributed hidden gems​

?user_added=true
&is_chain=false
&rating__gte=4.0
&ordering=-score_combined

Tips & Best Practices​

  1. Combine filters - Most filters can be used together for precise results
  2. Use location sorting - When using geo filters, sort by location for distance-based results
  3. Search vs Filter - Use search for text queries, filters for structured data
  4. Performance - Limit the number of filters when possible for faster queries
  5. Pagination - Always implement pagination for large result sets
  6. GeoJSON format - Use for map-based applications
  7. Fuzzy search - The search automatically handles typos, so users don't need exact spelling
  8. Multiple categories - Use __in for OR logic across categories, tags, or vibes

Lookup Reference​

Available Lookup Suffixes​

SuffixDescriptionExample
(none)Exact match?city=Boston
__inMatch any of (OR)?categories__in=bar,club
__excludeDoes not match?tags__exclude=loud
__prefixStarts with?categories__prefix=rest
__wildcardContains pattern?name__wildcard=*coffee*
__gtGreater than?rating__gt=4.0
__gteGreater than or equal?price__gte=2
__ltLess than?rating__lt=3.0
__lteLess than or equal?price__lte=2
__rangeBetween values?rating__range=3.5__5.0
__geo_distanceWithin distance?location__geo_distance=5km__lat,lon
__geo_bounding_boxWithin rectangleSee geo filters above
__geo_polygonWithin polygonSee geo filters above

Error Handling​

Common errors and solutions:

  • Invalid coordinates - Check latitude (-90 to 90) and longitude (-180 to 180) ranges
  • Invalid distance unit - Use km, mi, or m
  • Unknown field - Check parameter spelling against this guide
  • No results - Try removing filters or broadening search terms
  • Too many results - Add more filters or use pagination

Questions or Issues?​

For API support or feature requests, contact the Vibemap development team or check the project documentation.