{ "openapi": "3.1.0", "info": { "title": "GoogleMapsAPI.io — Real-Time Google Maps Places, Reviews & Lead Enrichment API", "version": "1.0.0", "description": "High-throughput REST API for Google Maps local business search, bounding-box & radius discovery, full place details, verified customer reviews, photos, autocomplete, reverse geocoding, and website email/social lead enrichment. Unified credit billing ($1 = 10,000 Credits, from $0.20 per 1,000 places)." }, "servers": [ { "url": "https://api.googlemapsapi.io", "description": "Production Global Edge API Gateway" } ], "tags": [ { "name": "Place Search & Discovery", "description": "Natural-language text search and geographic radius / bounding-box discovery across 200M+ Google Maps businesses." }, { "name": "Business Details & Media", "description": "Full Google Business Profile metadata, verified customer reviews, owner replies, and high-resolution storefront photos." }, { "name": "B2B Contact Enrichment", "description": "Website email extraction, direct phone verification, and social profile discovery across 8 platforms." }, { "name": "Geocoding & Autocomplete", "description": "Real-time typeahead place predictions and reverse geocoding from GPS coordinates to street addresses." } ], "paths": { "/v1/places/search": { "get": { "operationId": "v1_places_search", "summary": "Google Maps Text Search", "description": "Search Google Maps local businesses by natural-language query (e.g., 'coffee shops in SoHo, New York' or 'emergency plumbers in Austin, TX'). Returns structured business profiles including place_id, cid, phone number, website domain, rating, review count, opening hours, price level, and GPS coordinates.", "tags": [ "Place Search & Discovery" ], "x-credits-per-request": "5 Credits / place (min 10; 0 if empty)", "x-price-per-request": "$0.0005 / place ($0.20–$0.50 / 1K places)", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Free-text search query including business category and location (e.g., 'coffee shops in SoHo, New York').", "example": "coffee shops in SoHo, New York", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Optional latitude coordinate to bias search results (-90 to 90).", "example": 40.7233, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "required": false, "description": "Optional longitude coordinate to bias search results (-180 to 180).", "example": -74.003, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "zoom", "in": "query", "required": false, "description": "Map viewport zoom level (3 to 21, default 14).", "example": 14, "schema": { "type": "integer", "minimum": 3, "maximum": 21, "default": 14 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of businesses to return (1 to 100, default 20).", "example": 20, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "region", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code (e.g., 'us', 'gb', 'de').", "example": "us", "schema": { "type": "string", "default": "us" } }, { "name": "language", "in": "query", "required": false, "description": "ISO 639-1 language code for localized names and categories (default 'en').", "example": "en", "schema": { "type": "string", "default": "en" } }, { "name": "fresh", "in": "query", "required": false, "description": "Bypass the 30-day PostgreSQL index cache and force a live upstream Google Maps SERP fetch.", "example": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Paginated list of matching Google Maps business profiles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceSearchResponse" }, "example": { "request_id": "req_gm_99281a7bc102", "status": "ok", "data": [ { "place_id": "ChIJN5X_gWdZwokRck9rk2guJ1M", "google_id": "0x89c2596781ff9537:0x53272e68936b4f72", "cid": "5991807586670235506", "name": "Felix Roasting Co.", "primary_category": "Coffee shop", "categories": [ "Coffee shop", "Cafe", "Espresso bar" ], "rating": 4.5, "review_count": 782, "price_level": "$$", "phone": "+1 212-359-1139", "phone_e164": "+12123591139", "website": "https://felixroastingco.com", "domain": "felixroastingco.com", "address": { "formatted": "450 Broome St, New York, NY 10013", "street": "450 Broome St", "city": "New York", "state": "New York", "postal_code": "10013", "country_code": "US", "plus_code": "87G7PXXW+8Q" }, "coordinates": { "latitude": 40.722341, "longitude": -74.001298 }, "business_status": "OPERATIONAL", "is_claimed": true, "google_maps_url": "https://www.google.com/maps/place/?q=place_id:ChIJN5X_gWdZwokRck9rk2guJ1M" } ], "meta": { "credits_used": 10, "credits_remaining": 1990, "count": 1, "has_more": false, "next_cursor": null, "cache_hit": false } } } } } } } }, "/v1/places/nearby": { "get": { "operationId": "v1_places_nearby", "summary": "Nearby & Bounding-Box Search", "description": "Discover Google Maps businesses inside a geographic viewport around exact GPS coordinates (lat, lng, zoom) or within an explicit bounding box (min_lat, min_lng, max_lat, max_lng). Ideal for grid-based territory scraping.", "tags": [ "Place Search & Discovery" ], "x-credits-per-request": "5 Credits / place (min 10; 0 if empty)", "x-price-per-request": "$0.0005 / place ($0.20–$0.50 / 1K places)", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Category or keyword to search within the target coordinates (e.g., 'italian restaurant', 'HVAC contractor').", "example": "italian restaurant", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": true, "description": "Center latitude coordinate (-90 to 90).", "example": 40.7233, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "required": true, "description": "Center longitude coordinate (-180 to 180).", "example": -74.003, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "zoom", "in": "query", "required": false, "description": "Map viewport zoom level (3 to 21, default 15).", "example": 15, "schema": { "type": "integer", "minimum": 3, "maximum": 21, "default": 15 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of businesses to return (1 to 100, default 20).", "example": 20, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Businesses discovered inside the target coordinate viewport.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceSearchResponse" }, "example": { "request_id": "req_gm_88412b9dc401", "status": "ok", "data": [ { "place_id": "ChIJV2-tVGZZwokR9_3p246G5u8", "google_id": "0x89c2596654ad6f57:0xefe6868edb69fdf7", "cid": "17286646819044163063", "name": "Balthazar", "primary_category": "French restaurant", "categories": [ "French restaurant", "Bistro", "Bakery" ], "rating": 4.4, "review_count": 5690, "price_level": "$$$", "phone": "+1 212-965-1414", "phone_e164": "+12129651414", "website": "https://balthazarny.com", "domain": "balthazarny.com", "address": { "formatted": "80 Spring St, New York, NY 10012", "street": "80 Spring St", "city": "New York", "state": "New York", "postal_code": "10012", "country_code": "US", "plus_code": "87G7PXXW+3V" }, "coordinates": { "latitude": 40.722647, "longitude": -73.998229 }, "business_status": "OPERATIONAL", "is_claimed": true, "google_maps_url": "https://www.google.com/maps/place/?q=place_id:ChIJV2-tVGZZwokR9_3p246G5u8" } ], "meta": { "credits_used": 10, "credits_remaining": 1980, "count": 1, "has_more": false, "next_cursor": null, "cache_hit": false } } } } } } } }, "/v1/places/details": { "get": { "operationId": "v1_places_details", "summary": "Place Details & Full Business Profile", "description": "Retrieve the complete Google Business Profile by place_id, cid, or google_id. Includes verified contact info, rating breakdown (1-star to 5-star counts), full weekly opening hours, service attributes, and cached website contact enrichment.", "tags": [ "Business Details & Media" ], "x-credits-per-request": "20 Credits / business profile", "x-price-per-request": "$0.002 / profile ($0.80–$2.00 / 1K profiles)", "parameters": [ { "name": "place_id", "in": "query", "required": true, "description": "Google Maps Place ID (e.g., 'ChIJN5X_gWdZwokRck9rk2guJ1M'), numeric CID, or hex Google ID.", "example": "ChIJN5X_gWdZwokRck9rk2guJ1M", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "ISO 639-1 language code (default 'en').", "example": "en", "schema": { "type": "string", "default": "en" } }, { "name": "fresh", "in": "query", "required": false, "description": "Bypass local PostgreSQL cache and fetch live from Google Maps.", "example": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Complete Google Business Profile object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceDetailsResponse" }, "example": { "request_id": "req_gm_77123c8ea901", "status": "ok", "data": { "place_id": "ChIJN5X_gWdZwokRck9rk2guJ1M", "google_id": "0x89c2596781ff9537:0x53272e68936b4f72", "cid": "5991807586670235506", "name": "Felix Roasting Co.", "description": "Ornate, high-design cafe serving artisanal espresso drinks, housemade non-dairy milks & pastries.", "primary_category": "Coffee shop", "categories": [ "Coffee shop", "Cafe", "Espresso bar", "Pastry shop" ], "rating": 4.5, "review_count": 782, "reviews_per_rating": { "1": 24, "2": 18, "3": 42, "4": 136, "5": 562 }, "price_level": "$$", "phone": "+1 212-359-1139", "phone_e164": "+12123591139", "website": "https://felixroastingco.com", "domain": "felixroastingco.com", "address": { "formatted": "450 Broome St, New York, NY 10013", "street": "450 Broome St", "city": "New York", "state": "New York", "postal_code": "10013", "country_code": "US", "plus_code": "87G7PXXW+8Q" }, "coordinates": { "latitude": 40.722341, "longitude": -74.001298 }, "business_status": "OPERATIONAL", "is_claimed": true, "working_hours": { "monday": [ "08:00–18:00" ], "tuesday": [ "08:00–18:00" ], "wednesday": [ "08:00–18:00" ], "thursday": [ "08:00–18:00" ], "friday": [ "08:00–18:00" ], "saturday": [ "08:30–18:30" ], "sunday": [ "08:30–18:30" ] }, "attributes": { "Service options": [ "Outdoor seating", "Takeout", "Dine-in" ], "Highlights": [ "Great coffee", "Great tea selection" ], "Accessibility": [ "Wheelchair accessible entrance" ] }, "contacts_enrichment": { "emails": [ "info@felixroastingco.com", "events@felixroastingco.com" ], "social_links": { "instagram": "https://www.instagram.com/felixroastingco", "facebook": "https://www.facebook.com/felixroastingco" } }, "google_maps_url": "https://www.google.com/maps/place/?q=place_id:ChIJN5X_gWdZwokRck9rk2guJ1M" }, "meta": { "credits_used": 20, "credits_remaining": 1960, "count": 1, "has_more": false, "next_cursor": null, "cache_hit": false } } } } } } } }, "/v1/places/reviews": { "get": { "operationId": "v1_places_reviews", "summary": "Place Customer Reviews & Owner Replies", "description": "Fetch verified customer reviews for any Google Maps business by place_id or cid. Supports sorting by newest, highest_rating, lowest_rating, or most_relevant, plus keyword filtering.", "tags": [ "Business Details & Media" ], "x-credits-per-request": "2 Credits / review (min 10; 0 if empty)", "x-price-per-request": "$0.0002 / review ($0.08–$0.20 / 1K reviews)", "parameters": [ { "name": "place_id", "in": "query", "required": true, "description": "Google Maps Place ID or numeric CID.", "example": "ChIJN5X_gWdZwokRck9rk2guJ1M", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order: 'most_relevant', 'newest', 'highest_rating', or 'lowest_rating'.", "example": "newest", "schema": { "type": "string", "enum": [ "most_relevant", "newest", "highest_rating", "lowest_rating" ], "default": "newest" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of reviews to return (1 to 100, default 20).", "example": 20, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "query", "in": "query", "required": false, "description": "Optional keyword filter to match inside review text (e.g., 'espresso', 'service').", "example": "espresso", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of verified customer reviews with author metadata and owner responses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceReviewsResponse" }, "example": { "request_id": "req_gm_66109d2fa118", "status": "ok", "data": [ { "review_id": "ChdDSUhNMG9nS0VJQ0FnSUR4cE95djlBRRAB", "place_id": "ChIJN5X_gWdZwokRck9rk2guJ1M", "rating": 5, "review_text": "Hands down the most stunning coffee shop interior in Manhattan. The Hickory Smoked S'mores Latte and housemade almond milk espresso are incredible.", "published_at": "2026-10-28T14:22:10Z", "relative_time": "a week ago", "likes_count": 4, "author": { "name": "Elena Rostova", "profile_url": "https://www.google.com/maps/contrib/10829481928374", "avatar_url": "https://lh3.googleusercontent.com/a-/ALV-UjX8291", "is_local_guide": true, "total_reviews": 148 }, "owner_response": { "text": "Thank you so much for visiting us in SoHo, Elena! Thrilled you loved the Smoked S'mores Latte.", "published_at": "2026-10-29T09:15:00Z" }, "images": [ "https://lh5.googleusercontent.com/p/AF1QipN928172_felix_latte" ] } ], "meta": { "credits_used": 10, "credits_remaining": 1950, "count": 1, "has_more": true, "next_cursor": "CAESY0NBRVFDaHBFUTJwRlNVRlNTWEJEWjI5QlVEY3lTR2R4", "cache_hit": false } } } } } } } }, "/v1/places/photos": { "get": { "operationId": "v1_places_photos", "summary": "Place High-Resolution Photos", "description": "Retrieve high-resolution photo URLs, dimensions, categories (exterior, interior, food & drink, menu), and contributor attribution for a Google Maps business.", "tags": [ "Business Details & Media" ], "x-credits-per-request": "2 Credits / photo (min 6; 0 if empty)", "x-price-per-request": "$0.0002 / photo ($0.08–$0.20 / 1K photos)", "parameters": [ { "name": "place_id", "in": "query", "required": true, "description": "Google Maps Place ID or numeric CID.", "example": "ChIJN5X_gWdZwokRck9rk2guJ1M", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of photos to return (1 to 50, default 20).", "example": 20, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "List of high-resolution business photos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacePhotosResponse" }, "example": { "request_id": "req_gm_55012e9ab304", "status": "ok", "data": [ { "photo_id": "AF1QipN928172_felix_interior", "place_id": "ChIJN5X_gWdZwokRck9rk2guJ1M", "url": "https://lh5.googleusercontent.com/p/AF1QipN928172_felix_interior=w1600-h1200-k-no", "thumbnail_url": "https://lh5.googleusercontent.com/p/AF1QipN928172_felix_interior=w400-h300-k-no", "width": 1600, "height": 1200, "category": "Interior", "author_name": "Felix Roasting Co.", "uploaded_at": "2026-08-14T12:00:00Z" } ], "meta": { "credits_used": 6, "credits_remaining": 1944, "count": 1, "has_more": false, "next_cursor": null, "cache_hit": false } } } } } } } }, "/v1/leads/enrich": { "get": { "operationId": "v1_leads_enrich", "summary": "Website Email, Phone & Social Lead Enrichment", "description": "Crawl a business website domain (or look up by place_id) to extract verified B2B email addresses, direct phone numbers, contact page URLs, and social media profiles across LinkedIn, Instagram, Facebook, X/Twitter, YouTube, TikTok, Pinterest, and GitHub. Charges 0 Credits if no emails or social links are found.", "tags": [ "B2B Contact Enrichment" ], "x-credits-per-request": "20 Credits / enriched domain (0 if none found)", "x-price-per-request": "$0.002 / enriched domain ($0.80–$2.00 / 1K leads)", "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Business website domain or URL (e.g., 'felixroastingco.com' or 'bluebottlecoffee.com').", "example": "felixroastingco.com", "schema": { "type": "string" } }, { "name": "place_id", "in": "query", "required": false, "description": "Optional Google Maps Place ID to link enriched contacts back to the stored business profile.", "example": "ChIJN5X_gWdZwokRck9rk2guJ1M", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Extracted emails, phone numbers, and social profiles for the target domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadEnrichResponse" }, "example": { "request_id": "req_gm_44918f7cd209", "status": "ok", "data": { "domain": "felixroastingco.com", "place_id": "ChIJN5X_gWdZwokRck9rk2guJ1M", "emails": [ { "email": "info@felixroastingco.com", "type": "general", "source_page": "https://felixroastingco.com/pages/contact" }, { "email": "events@felixroastingco.com", "type": "sales", "source_page": "https://felixroastingco.com/pages/private-events" } ], "phones": [ "+12123591139" ], "contact_page_url": "https://felixroastingco.com/pages/contact", "social_links": { "instagram": "https://www.instagram.com/felixroastingco", "facebook": "https://www.facebook.com/felixroastingco", "linkedin": "https://www.linkedin.com/company/felix-roasting-co", "twitter": null, "tiktok": null, "youtube": null }, "scraped_at": "2026-11-04T22:45:00Z" }, "meta": { "credits_used": 20, "credits_remaining": 1924, "count": 1, "has_more": false, "next_cursor": null, "cache_hit": false } } } } } } } }, "/v1/places/autocomplete": { "get": { "operationId": "v1_places_autocomplete", "summary": "Place & Address Typeahead Autocomplete", "description": "Real-time typeahead predictions for businesses, street addresses, cities, and landmarks with optional coordinate and country biasing.", "tags": [ "Geocoding & Autocomplete" ], "x-credits-per-request": "5 Credits / request", "x-price-per-request": "$0.0005 / request ($0.20–$0.50 / 1K calls)", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Partial text input from the user (e.g., '1600 Amphitheatre' or 'Felix Roast').", "example": "1600 Amphitheatre", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code restriction (e.g., 'US').", "example": "US", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "required": false, "description": "Optional latitude for proximity biasing.", "example": 37.422, "schema": { "type": "number" } }, { "name": "lng", "in": "query", "required": false, "description": "Optional longitude for proximity biasing.", "example": -122.084, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Ordered list of typeahead place and address predictions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteResponse" }, "example": { "request_id": "req_gm_33817a4bc110", "status": "ok", "data": [ { "place_id": "ChIJtYuu0V25j4ARwu5e4wwRYgE", "description": "1600 Amphitheatre Parkway, Mountain View, CA, USA", "main_text": "1600 Amphitheatre Parkway", "secondary_text": "Mountain View, CA, USA", "types": [ "street_address", "geocode" ], "coordinates": { "latitude": 37.4220656, "longitude": -122.0840897 } } ], "meta": { "credits_used": 5, "credits_remaining": 1919, "count": 1, "has_more": false, "next_cursor": null, "cache_hit": false } } } } } } } }, "/v1/geocode/reverse": { "get": { "operationId": "v1_geocode_reverse", "summary": "Reverse Geocoding (Coordinates to Address)", "description": "Convert raw GPS latitude and longitude coordinates into structured street addresses, postal codes, administrative areas, and corresponding Google Maps Place IDs.", "tags": [ "Geocoding & Autocomplete" ], "x-credits-per-request": "5 Credits / request", "x-price-per-request": "$0.0005 / request ($0.20–$0.50 / 1K calls)", "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude coordinate (-90 to 90).", "example": 40.722341, "schema": { "type": "number", "minimum": -90, "maximum": 90 } }, { "name": "lng", "in": "query", "required": true, "description": "Longitude coordinate (-180 to 180).", "example": -74.001298, "schema": { "type": "number", "minimum": -180, "maximum": 180 } }, { "name": "language", "in": "query", "required": false, "description": "ISO 639-1 language code (default 'en').", "example": "en", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Structured address components and matching place_ids for the coordinates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseGeocodeResponse" }, "example": { "request_id": "req_gm_22901b8de512", "status": "ok", "data": [ { "place_id": "ChIJN5X_gWdZwokRck9rk2guJ1M", "formatted_address": "450 Broome St, New York, NY 10013, USA", "address_components": { "street_number": "450", "route": "Broome St", "neighborhood": "SoHo", "locality": "New York", "administrative_area_level_1": "NY", "postal_code": "10013", "country_code": "US" }, "coordinates": { "latitude": 40.722341, "longitude": -74.001298 }, "plus_code": "87G7PXXW+8Q" } ], "meta": { "credits_used": 5, "credits_remaining": 1914, "count": 1, "has_more": false, "next_cursor": null, "cache_hit": false } } } } } } } } }, "components": { "schemas": { "ResponseMeta": { "type": "object", "properties": { "credits_used": { "type": "integer", "description": "Credits deducted for this API call." }, "credits_remaining": { "type": "integer", "description": "Remaining credit balance on the account." }, "count": { "type": "integer", "description": "Number of records returned in data." }, "has_more": { "type": "boolean", "description": "Whether additional pages are available." }, "next_cursor": { "type": "string", "description": "Opaque cursor token for fetching the next page." }, "cache_hit": { "type": "boolean", "description": "Whether the response was served from the sub-50ms local index." } } }, "AddressObject": { "type": "object", "properties": { "formatted": { "type": "string", "description": "Full human-readable street address." }, "street": { "type": "string", "description": "Street number and street name." }, "city": { "type": "string", "description": "City or locality." }, "state": { "type": "string", "description": "State, province, or region." }, "postal_code": { "type": "string", "description": "ZIP or postal code." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "plus_code": { "type": "string", "description": "Google Open Location Code (Plus Code)." } } }, "CoordinatesObject": { "type": "object", "properties": { "latitude": { "type": "number", "description": "WGS84 latitude coordinate." }, "longitude": { "type": "number", "description": "WGS84 longitude coordinate." } } }, "PlaceSummary": { "type": "object", "properties": { "place_id": { "type": "string", "description": "Unique Google Maps Place ID (ChIJ...)." }, "google_id": { "type": "string", "description": "Hexadecimal Google feature ID (0x...:0x...)." }, "cid": { "type": "string", "description": "Numeric Google Customer ID (CID)." }, "name": { "type": "string", "description": "Official business title on Google Maps." }, "primary_category": { "type": "string", "description": "Primary business category." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "All assigned business categories." }, "rating": { "type": "number", "description": "Aggregate star rating (1.0 to 5.0)." }, "review_count": { "type": "integer", "description": "Total number of Google Maps user reviews." }, "price_level": { "type": "string", "description": "Price tier indicator ($ to $$$$)." }, "phone": { "type": "string", "description": "Formatted local phone number." }, "phone_e164": { "type": "string", "description": "E.164 international phone number." }, "website": { "type": "string", "description": "Official business website URL." }, "domain": { "type": "string", "description": "Normalized root domain." }, "address": { "$ref": "#/components/schemas/AddressObject" }, "coordinates": { "$ref": "#/components/schemas/CoordinatesObject" }, "business_status": { "type": "string", "description": "OPERATIONAL, CLOSED_TEMPORARILY, or CLOSED_PERMANENTLY." }, "is_claimed": { "type": "boolean", "description": "Whether the Google Business Profile is owner-verified." }, "google_maps_url": { "type": "string", "description": "Direct link to the place on Google Maps." } } }, "PlaceSearchResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique request trace identifier." }, "status": { "type": "string", "description": "Response status ('ok')." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlaceSummary" }, "description": "Matching business profiles." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "PlaceDetailsResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique request trace identifier." }, "status": { "type": "string", "description": "Response status ('ok')." }, "data": { "$ref": "#/components/schemas/PlaceSummary", "description": "Full Google Business Profile with hours, attributes, and enriched contacts." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ReviewItem": { "type": "object", "properties": { "review_id": { "type": "string", "description": "Unique Google review identifier." }, "place_id": { "type": "string", "description": "Associated Google Maps Place ID." }, "rating": { "type": "integer", "description": "Star rating from 1 to 5." }, "review_text": { "type": "string", "description": "Full customer review text." }, "published_at": { "type": "string", "description": "ISO 8601 publication timestamp." }, "relative_time": { "type": "string", "description": "Human-readable relative age (e.g., '2 weeks ago')." }, "likes_count": { "type": "integer", "description": "Number of helpful votes on the review." }, "images": { "type": "array", "items": { "type": "string" }, "description": "Customer-uploaded review photo URLs." } } }, "PlaceReviewsResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique request trace identifier." }, "status": { "type": "string", "description": "Response status ('ok')." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewItem" }, "description": "Verified customer reviews." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "PhotoItem": { "type": "object", "properties": { "photo_id": { "type": "string", "description": "Unique photo identifier." }, "place_id": { "type": "string", "description": "Associated Google Maps Place ID." }, "url": { "type": "string", "description": "High-resolution direct image URL." }, "thumbnail_url": { "type": "string", "description": "Thumbnail image URL." }, "width": { "type": "integer", "description": "Image width in pixels." }, "height": { "type": "integer", "description": "Image height in pixels." }, "category": { "type": "string", "description": "Photo classification (Interior, Exterior, Menu, Food & drink)." }, "author_name": { "type": "string", "description": "Uploader display name." }, "uploaded_at": { "type": "string", "description": "ISO 8601 upload timestamp." } } }, "PlacePhotosResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique request trace identifier." }, "status": { "type": "string", "description": "Response status ('ok')." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoItem" }, "description": "Business photos." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "LeadEnrichData": { "type": "object", "properties": { "domain": { "type": "string", "description": "Normalized target domain." }, "place_id": { "type": "string", "description": "Linked Google Maps Place ID (if provided)." }, "emails": { "type": "array", "description": "Extracted business email addresses and source pages.", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Verified email address." }, "type": { "type": "string", "description": "Classification ('general', 'sales', 'support', 'personal')." }, "source_page": { "type": "string", "description": "URL where the email was discovered." } } } }, "phones": { "type": "array", "items": { "type": "string" }, "description": "Extracted E.164 phone numbers." }, "contact_page_url": { "type": "string", "description": "Discovered contact page URL." }, "scraped_at": { "type": "string", "description": "ISO 8601 timestamp of extraction." } } }, "LeadEnrichResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique request trace identifier." }, "status": { "type": "string", "description": "Response status ('ok')." }, "data": { "$ref": "#/components/schemas/LeadEnrichData" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "AutocompletePrediction": { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID." }, "description": { "type": "string", "description": "Full prediction label." }, "main_text": { "type": "string", "description": "Primary place or street name." }, "secondary_text": { "type": "string", "description": "City, state, and country context." }, "types": { "type": "array", "items": { "type": "string" }, "description": "Place classification tags." }, "coordinates": { "$ref": "#/components/schemas/CoordinatesObject" } } }, "AutocompleteResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique request trace identifier." }, "status": { "type": "string", "description": "Response status ('ok')." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutocompletePrediction" }, "description": "Typeahead predictions." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } }, "ReverseGeocodeResult": { "type": "object", "properties": { "place_id": { "type": "string", "description": "Nearest Google Maps Place ID." }, "formatted_address": { "type": "string", "description": "Formatted street address." }, "coordinates": { "$ref": "#/components/schemas/CoordinatesObject" }, "plus_code": { "type": "string", "description": "Open Location Code." } } }, "ReverseGeocodeResponse": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique request trace identifier." }, "status": { "type": "string", "description": "Response status ('ok')." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReverseGeocodeResult" }, "description": "Reverse geocoded addresses." }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } } } } } }