Almanac by PassBy

Find a location based on an address or description using geocoding.

This tool geocodes the provided address/description to coordinates, then searches for nearby locations in the database.

Args: description: Address or location description (e.g., "1234 Pike Street, Seattle, WA" or "Starbucks near Times Square, New York") brand_name: Optional brand name to filter results (e.g., "Starbucks", "McDonald's"). If not provided, the tool will attempt to extract it from the description. radius_miles: Search radius in miles (default: 1.0, max: 10) limit: Maximum number of results to return (default: 10, max: 50) include_closed: If True, include locations that have closed (default: False)

Returns: List of matching locations sorted by distance from the geocoded point

Examples:

• "1234 Pike Street, Seattle, WA"
• "Starbucks at 123 Main Street, Chicago, IL"
• "Times Square, New York, NY"

Find locations near a geographic point.

Provide EITHER an address OR latitude/longitude coordinates.

Args: address: Street address to search near (e.g., '123 Main St, Seattle, WA') latitude: Latitude coordinate (use with longitude) longitude: Longitude coordinate (use with latitude) radius_miles: Search radius in miles (default: 10, max: 50) brand_name: Optional brand filter (e.g., 'Starbucks') category: Optional category filter (e.g., 'Coffee Shop') limit: Maximum results (default: 20, max: 50) include_closed: If True, include locations that have closed (default: False)

Returns: List of nearby locations sorted by distance

Get comprehensive information about a brand.

Args: brand: Brand name (e.g., 'Starbucks') or brand ID (e.g., 'SG_BRAND_123') include_closed: If True, include closed locations in counts (default: False)

Returns: Brand information including name, location count, categories, and geographic distribution

Get visits for individual store locations within a brand.

Args: brand: Brand name (e.g., 'Starbucks') or brand ID (e.g., 'SG_BRAND_123') start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format comparison_type: 'total' for raw visits, 'yoy' for year-over-year comparison top_n: Optional

• Return only top N locations by visits

bottom_n: Optional

• Return only bottom N locations by visits

city: Optional

• Filter by city name

state: Optional

• Filter by state code (e.g., 'CA', 'TX')

include_closed: If True, include locations that have closed (default: False)

Returns: List of store locations with their visit data

Get visitor demographic segments for a brand (aggregated across all locations).

Args: brand: Brand name (e.g., 'Starbucks') or brand ID (e.g., 'SG_BRAND_123') dataset: Demographic segment type - 'age', 'income' (default), 'education', 'tenure', or 'industry' start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format comparison_type: 'total' for percentages, 'state' or 'nation' for difference with reference

Returns: Visitor segment data with percentages and human-readable segment names

Get foot traffic visits for a brand over a date range.

Args: brand: Brand name (e.g., 'Starbucks') or brand ID (e.g., 'SG_BRAND_123') start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format granularity: Time granularity - 'daily', 'weekly', or 'monthly' comparison_type: 'total' for raw visits, 'yoy' for year-over-year comparison

Returns: Visit data by time period with optional YoY comparison

Get comprehensive information about a specific location.

Args: location_id: Location identifier (UUID format, e.g., '36c628b0-692e-4645-b328-64b50004eb09') include_closed: If True, include locations that have closed (default: False)

Returns: Location information including name, address, brand, categories, and geographic coordinates

Get visitor demographic segments for a specific location.

Args: location_id: Location identifier (UUID format) dataset: Demographic segment type - 'age', 'income' (default), 'education', 'tenure', or 'industry' start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format comparison_type: 'total' for percentages, 'state' or 'nation' for difference with reference

Returns: Visitor segment data with percentages and human-readable segment names

Get foot traffic visits for a specific location over a date range.

Args: location_id: Location identifier (UUID format, e.g., '285e9c67-1c16-4335-9a45-2570503fe5e1') start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format granularity: Time granularity - 'daily', 'weekly', or 'monthly' comparison_type: 'total' for raw visits, 'yoy' for year-over-year comparison

Returns: Visit data by time period with optional YoY comparison

Get details about a specific market/shopping center.

Args: market_id: Market identifier (UUID format, e.g., '36c628b0-692e-4645-b328-64b50004eb09')

Returns: Market information including name, type, location

Get list of tenant stores within a market/shopping center.

Args: market_id: Market identifier (UUID format) limit: Maximum number of tenants to return (default: 50, max: 100) include_closed: If True, include closed tenant locations (default: False)

Returns: List of tenant location details

Get visitor demographics for a market/shopping center.

Args: market_id: Market identifier (UUID format) dataset: Demographic segment type - 'age', 'income' (default), 'education', 'tenure', or 'industry' start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format

Returns: Visitor demographic segments with percentages and human-readable segment names

Get foot traffic visits for a market/shopping center over time.

Args: market_id: Market identifier (UUID format) start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format granularity: Time granularity - 'daily', 'weekly', or 'monthly' comparison_type: 'total' for raw visits, 'yoy' for year-over-year comparison

Returns: Visit data by time period

Search for brands by name using semantic similarity.

Uses ML embeddings and vector search to find brands that match the provided name. Returns brands ranked by similarity (lower distance = higher similarity).

Args: brand_name: Brand name to search for (e.g., "Starbucks", "McDonald's", "coffee shop") top_k: Number of top matches to return (default: 10, max: 20)

Returns: List of matching brands with their IDs and similarity scores

Search for shopping centers and malls by name, location, or proximity.

Supports text-based filters (name, city, state, market_type) and/or geographic search via address or coordinates. When an address or coordinates are provided, results are sorted by distance.

Args: name: Market name to search for (partial match, e.g., 'Westfield', 'Plaza') city: City name to filter by (e.g., 'San Francisco', 'Los Angeles') state: State code to filter by (e.g., 'CA', 'TX', 'NY') market_type: Market type to filter by (e.g., 'RETAIL_CENTERS', 'RETAIL_CLUSTERS') address: Street address to search near (will geocode to coordinates) latitude: Latitude coordinate (use with longitude) longitude: Longitude coordinate (use with latitude) radius_miles: Search radius in miles when using address/coordinates (default: 25, max: 50) limit: Maximum number of results to return (default: 20, max: 50)

Returns: List of matching markets with their IDs and details