# SafeGraph MCP > SafeGraph lets you analyze complex geographic data using natural language. It connects your AI to a massive dataset of Points of Interest (POIs), building geometries, and historical foot traffic patterns worldwide. You can query specific brands, find all locations within a radius, or map the precise footprint of any structure simply by asking questions. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** geospatial-data, poi-data, foot-traffic-analysis, location-intelligence, demographics, data-mapping ## Description Need to know what's physically happening in an area? This connection gives your AI expert-level geographic analysis without ever touching complex database queries. It turns general questions into highly detailed location intelligence. You can find every coffee shop within a half-mile radius or map the exact polygon of a building using its Placekey. Furthermore, you gain access to historical data, letting you check foot traffic volumes and average visitor dwell times for any structure over time. This deep capability is available instantly via Vinkius, making it one of the most powerful geospatial datasets in the catalog. It’s pure analytical power, giving your agent the ability to act like a professional urban planner or retail analyst. ## Tools ### batch_lookup_placekeys Performs multiple Placekey lookups efficiently using a single JSON array input. ### graphql_raw_query Executes any raw GraphQL query against the SafeGraph API for complex data retrieval. ### lookup_building_geometry Retrieves the exact polygon coordinates defining a specific building's physical footprint. ### lookup_parent_polygon Identifies and maps the encompassing parent location, such as an airport or mall, for any given site. ### lookup_place_patterns Retrieves historical data showing pedestrian foot traffic volumes and average dwell times at a specific location. ### lookup_placekey Gets detailed attribute information for any known location using its unique Placekey ID. ### search_brand_places Searches for all locations belonging to a specific brand within a defined city boundary. ### search_distance_radius Finds places that fall within a specified radius from given latitude and longitude coordinates. ### search_industry_naics Searches for locations using specific NAICS industry codes combined with a regional filter. ### search_wkt_polygon Finds all places contained within an area defined by a custom geometric polygon (WKT format). ## Prompt Examples **Prompt:** ``` Search for all the Starbucks branches strictly inside the city of Seattle, WA. ``` **Response:** ``` I've successfully queried SafeGraph places. Found 50 highly visible Starbucks locations associated inside Seattle, providing the unique Placekey IDs sequentially for each site mapped correctly. ``` **Prompt:** ``` Check what the detailed building geometry polygon is for Placekey '22m-xyz-1234'. ``` **Response:** ``` I executed a targeted building geometry lookup securely. The geometric bounding lines forming the structure of site '22m-xyz-1234' are POLYGON((-122.123 47.982, ...)), completely reflecting its physical real-world footprint mapped securely. ``` **Prompt:** ``` Can you gather the historical pedestrian traffic patterns evaluating typical visit frequencies around Placekey '123-abc-987'? ``` **Response:** ``` The foot traffic data has been cleanly retrieved from the registry! Based on safe historical compilations, this location captures an approximate volume of 12,000 visitors routinely holding a median dwell time reaching precisely 45 minutes on active days. ``` ## Capabilities ### Identify specific local businesses Search for all locations belonging to a particular brand or industry within defined geographical boundaries. ### Map building footprints and borders Retrieve the precise geometric polygon for an individual building, or search for all places contained inside a custom-drawn city border. ### Analyze historical movement patterns Get metrics on foot traffic volume, typical visit frequency, and how long people stay at specific locations over time. ### Query complex spatial regions Perform broad searches for places based on NAICS industry codes or by passing a custom geographic polygon (WKT). ## Use Cases ### Checking Competitor Density A retail client needs to know where all their major competitors are located in a potential new market. They ask the agent, 'Find all locations for Best Buy and Target within 1 mile of this intersection.' The agent uses `search_distance_radius` and returns both lists, allowing immediate competitive mapping. ### Analyzing Site Potential An urban planner needs to understand the structural relationships in a large commercial district. They ask the agent about a major shopping center's container structure. The agent runs `lookup_parent_polygon` and confirms the overall boundaries, helping map development. ### Understanding Customer Behavior A museum director wants to gauge visitor interest in specific exhibits. They ask the agent for historical foot traffic data on a certain hall's Placekey. The agent runs `lookup_place_patterns` and reports low average dwell times, signaling a need for exhibit redesign. ### Bulk Location Data Retrieval A data scientist has 50 unique location IDs they want to analyze quickly. Instead of running 50 separate queries, the agent uses `batch_lookup_placekeys` in one call to retrieve all necessary attributes simultaneously. ## Benefits - You gain the ability to analyze specific brand concentrations. Instead of manually cross-referencing store maps, you can ask your agent to find all 'Starbucks' locations within Seattle instantly using `search_brand_places`. - The process of mapping structures becomes trivial. You don't need CAD software; just give your AI a Placekey and use `lookup_building_geometry` to pull the exact polygon coordinates for that site. - Understand human behavior, not just addresses. Using `lookup_place_patterns`, you can get historical data showing if a location has high foot traffic and what the typical dwell time is—critical intel for retail. - Complex geographic searches are handled in plain language. Need to know everything within 500 meters of a point? Use `search_distance_radius` and let your agent handle the math. - You can search by industry or custom boundaries using `search_industry_naics` or `search_wkt_polygon`. This lets you segment data that was previously siloed in different database tables. ## How It Works The bottom line is you stop writing SQL queries and start asking questions about the physical world. 1. Install the SafeGraph mapping block into your AI workspace and input your API key. 2. Your agent processes your natural language request, identifying the necessary location parameters (lat/lon, radius, brand name). 3. The MCP executes the correct geographical query against the SafeGraph dataset and returns structured data, like polygons or lists of POIs. ## Frequently Asked Questions **How do I find all locations for a specific brand using SafeGraph MCP?** You run `search_brand_places`. You just tell your agent the brand name (like Starbucks) and the city, and it returns every matching location in that area. **Can I analyze foot traffic with SafeGraph MCP?** Yes. Use `lookup_place_patterns` to retrieve historical data on how many people visited a place and what their average time spent there was. **What is the difference between using search_distance_radius and search_wkt_polygon?** `search_distance_radius` finds everything in a circle around one point. `search_wkt_polygon` lets you draw an irregular shape, like a specific neighborhood boundary, to find everything inside that custom area. **Does SafeGraph MCP handle complex queries?** It does. For ultimate flexibility, use the `graphql_raw_query` tool, which lets you pass any complex query directly to the API root structure.