Returns available credits (split into the monthly plan allowance, spent first, and the never-expiring wallet), daily spending cap, plan, and environment. Useful before running multi-step or expensive analyses to confirm the account has enough credits. Free (0 credits).

Finds calls this account has already made, with what was asked and what it cost. Free (0 credits).

USE THIS BEFORE BUYING DATA AGAIN. Every response this API has returned is kept, so "has this changed since last month?", "what did we see last time?" and "did we already check this?" are answerable from what has been paid for once. Running the original endpoint again to answer them charges full price for a second copy.

Filter by endpoint, by date range, and by what was asked: keyword, location, business_name and domain match the parameters of the original call, so "every AI Mode call for this keyword" is one search. Note that a sandbox key sees only sandbox calls, and if the account turned response logging off then params were not stored either and these filters find nothing. Values match exactly, not as substrings — "best plumber" and "best plumber near me" are different questions and are not merged.

Returns entries with request_id, endpoint, params, credits_used, status_code and created_at, newest first, but NOT the response bodies — they are large and a search is for finding the call. Pass a request_id to history_get for the answer itself.

Building a trend: search for the calls, then history_get each one. A month of daily AI Mode calls is 30 cheap reads instead of 30 paid ones.

Returns one past call in full, including the response body exactly as it was returned at the time. Free (0 credits).

Takes the request_id from any previous response, or the id from history_search. This is how you read an answer you already paid for rather than buying it again.

A null body is not an error and not a missing call: the call happened, and its cost and timing are still there. response_data_omitted is "not_stored" and deliberately does not guess which of four causes applied — logging off for the account, a body over the size limit, a non-JSON body, or an endpoint whose response is never stored.

Checks where businesses rank in Google's local pack for a keyword. Returns rank, name, cid, rating, reviews_count, address, phone, hours, website. Returns the top 3 by default; set depth for a deeper local ranking list (up to 60), and device to check desktop vs mobile. maps returns GPS coordinates and place_ids instead of CIDs. Costs 2 credits.

Use when you need the complete Google search results page in one call: organic listings, local pack, ads, People Also Ask, AI overview, LSA ads, and knowledge panel. Best for auditing overall search presence. Costs 2 credits.

Use when checking Google Guaranteed/Screened ads for service categories (home services, legal, etc.). Returns business names, ratings, and reviews from the LSA carousel on the Google results page; badge, years_in_business, phone and services are filled only when Google shows them there. Retries on the mobile SERP when desktop shows no LSAs; lsa_block_found: false means Google showed none for the query. Costs 2 credits.

Returns local map results with GPS coordinates — up to 60 listings with name, place_id, rating, reviews_count, address, phone, website, hours, lat/lng, and categories. Paid map pins are excluded from the ranking and listed in sponsored_results. If the first search returns nothing, the API automatically retries once with the city appended to the keyword (geo_fallback_applied: true, keyword_used shows the retried keyword). Unresolvable locations return a validation error instead of silently searching country-wide. local_pack returns just the top 3 with CIDs if that's all you need. Costs 2 credits.

Use when you need local listings with Google CID identifiers (instead of GPS coordinates from maps). Returns names, ratings, reviews, addresses, phone, hours, websites, and CIDs. Supports min_rating filter. Costs 2 credits.

Use when checking if Google shows an AI Overview for a keyword and what sources it cites. Returns has_ai_overview, asynchronous_ai_overview, summary_text, and cited_sources with URLs. Each cited source carries a position — the order the overview cited it, from 1, counted after duplicate pages collapse. asynchronous_ai_overview reports that Google rendered the overview after page load — this tool fetches those as well, so summary_text and cited_sources are populated either way. Costs 2 credits. May take 10-30 seconds — fetching an asynchronous overview is a second request to Google.

Use when getting the Google AI Mode (SGE) generated answer for a keyword. Returns ai_response text, local_businesses, reference links, and shopping items. Costs 2 credits. May take 10-30 seconds; Google generates the answer per request.

LOCAL BUSINESSES: on a local question Google recommends businesses inside the answer and we return them as local_businesses — rank, name, category, rating, reviews_count, address, website, domain, cid. Field names shared with /v1/serp/local-pack mean the same things; the sets differ in that this adds category and domain and has no hours. cid is an empty string when the Directions link was unreadable. Two differences from ai_scraper on chat_gpt: phone is always empty (Google renders a Call button and never sends the number), and cid is populated — Google's own identifier for the business, in decimal, which /v1/business/profile also takes. Match on cid rather than on name where you can.

REVIEW COUNTS ARE ROUNDED: Google abbreviates above a thousand, so reviews_count is 1200 where the exact figure is 1194. Do not compare it to a count from another endpoint and read the difference as change.

parse_status reports whether the businesses could be read: "ok", "no_businesses" when the answer named none, or "unparsed" when business cards were present and none could be read — which means Google changed the format. references is unreliable for citations: on some answers it carries real domains, on others every entry collapses to a google.com redirect, and it never names the businesses either way.

Checks how businesses rank on Apple Maps for a keyword. Use when the question is about Apple Maps, Siri, Apple Business Connect, or visibility on iPhone — Google local_pack does not cover these. Returns rank, name, address, phone, website, rating, reviews_count, categories, hours, coordinates, and platform_id (Apple's MUID, stable and worth keeping for later lookups). claimed: false means Apple states the listing has never been claimed in Apple Business Connect — report that as a finding, it is usually more actionable than any NAP mismatch. claimed: null means Apple said nothing about claim state; report it as unknown and never as claimed, because Apple only ever reports the unclaimed case. Ratings are normalized to a 5-point scale (Apple mixes 5-point and 100-point scales internally). data_source names who Apple credits for the record ("yelp", "foursquare"; empty when Apple credits no one) — when it is non-empty the record was ingested from that provider rather than supplied by the owner, so website often points at the provider's page and must NOT be reported as a NAP mismatch against the client's domain. A 502 mentioning results outside the requested location means Apple applied the location inconsistently and answered from elsewhere; retry once, and if it persists say Apple Maps data is unavailable for that city right now — never substitute a nearby city's rankings. Costs 3 credits.

Checks how businesses rank in Bing's local results for a keyword. Use when the question is about Bing, Bing Places, Copilot, or ChatGPT local recommendations — ChatGPT's web layer draws on Bing, so this is the closest measurable proxy for it. Returns rank, name, address, phone, website, hours, coordinates, and platform_id. Bing publishes no ratings or review counts on local results, so rating is null and reviews_count is 0 — that is a platform limitation, not missing data. claimed is always null: Bing gives no claimed/unclaimed signal. Costs 3 credits.

Fetches a business's Apple Maps listing (NAP, rating, categories, coordinates). Use when auditing Apple Business Connect or checking NAP consistency on Apple. matched:false means no Apple listing exists at all. A listing that exists but has claimed:false means it exists and was never claimed in Apple Business Connect — a different, very common finding. claimed:null means unknown, not claimed. Both are results worth reporting, not errors. Check data_source before reporting a website mismatch: a non-empty value ("yelp") means Apple ingested the record from that provider, so its website is the provider's page by design. The returned platform_id is Apple's MUID: pass it back as muid on later calls to skip the name-resolution search, which drops the cost from 5 credits to 3. Costs 5 credits (3 with muid).

Fetches a business's Bing Maps listing (NAP, rating, coordinates). Use when auditing Bing Places or checking NAP consistency on Bing. matched:false means no Bing listing was found, which usually means Bing Places was never claimed — a finding, not an error. Costs 3 credits.

Use when pulling one business's complete GBP data. Returns name, address, phone, website, hours, categories, photos_count, rating, reviews_count, description, attributes, cid, place_id, and verified status. If no exact match is found, returns matched=false with up to 5 suggestions from Google Maps including place_id for exact retry. Costs 5 credits.

Audits what's missing or weak on a Google Business Profile. Returns completeness_score (0-100), missing_fields, incomplete_fields, and specific recommendations. For the raw profile fields without scoring, business_profile returns them directly. Costs 5 credits.

Use when checking what questions people ask on a GBP and whether they have answers. Returns questions with text, author, date, and answers with upvotes. Costs 5 credits.

Use when discovering all businesses in a category and location (bulk discovery, not single business lookup). Returns name, rating, reviews_count, address, city, phone, website, place_id, lat/lng, and categories for each, searched within search_radius_km of the location (location_used echoes where). Costs 10 credits per 50 results.

Use when reading actual review text and owner replies for sentiment analysis or reply auditing. Returns text, rating, date, author_name, owner_reply for each review plus total_reviews and average_rating. For multi-location brands pass place_id (from business_profile) — name+location lookups can silently return empty. Costs 1 credit per 10 reviews. May take 10-30 seconds.

Analyzes review growth rate, rating changes, reply rate, and sentiment themes over time. Returns reviews_per_month, rating_trend, reply_rate, sentiment_themes, and monthly breakdown. For raw review text without trend analysis, see google_reviews. For multi-location brands pass place_id (from business_profile) — name+location lookups can silently return empty. Costs 6 credits. May take 10-30 seconds.

Compares ratings across Google + Trustpilot in one call. Returns per-platform rating, count, and trend, plus combined_rating and total_reviews. Covers both platforms; google_reviews covers Google alone. Costs 6 credits. May take 10-30 seconds.

Use when running a comprehensive local SEO check: SERP + profile + reviews + competitors in one call. Returns local_pack_position, organic_positions, rating, reviews_count, profile_completeness, review_velocity, competitors, and recommendations. Expensive (50 credits) -- confirm with user first. Async, takes 15-45 seconds.

Use when analyzing cross-platform review reputation with sentiment. Returns reputation_score, per-platform ratings, sentiment themes, response_rate, and recommendations. Costs 30 credits. May take 10-30 seconds.

Use when checking NAP (Name, Address, Phone) consistency across business directories (Yelp, BBB, Facebook, YellowPages, Angi, Houzz, Trustpilot and more). Returns consistency_score (0-100 partial-credit average over found listings; null when no listings found) and per-directory match details. Match fields are true (verified), false (conflicting value found), or null (listing found but the field isn't visible in search data, so it can't be verified). Every directory selected is scanned whether or not a listing exists there, so directories_checked always equals what was requested -- a business listed on only a handful still returns a row per directory. Scans the top 20 directories by default (50 credits); directories takes a count up to 50 or an explicit list of directory names, and costs 2.5 credits each (all 50 = 125 credits). Expensive -- confirm with user first.

Use when mapping where a business ranks across a geographic area. Read-only: it checks public Google Maps rankings at each point of a grid and changes nothing. Ranks count organic listings only (ads are skipped), top 20. Returns: grid (2D array, 0 = not found), grid_points (flat array with row, col, lat, lng, rank, status -- use for map plotting), center, average_rank (ARP), atrp (not found = 21), solv (% of points in the top 3), found_in, failed_points, total_points. Set include_listings to also get the top 20 businesses at every point (competitor analysis). Expensive: 2 cr per point -- 18 cr (3x3), 50 cr (5x5, the default), 98 cr (7x7), 162 cr (9x9); confirm with user first. Points that could not be checked are refunded. Usually takes 30-60 seconds; this tool waits for the result.

IF THE RESULT IS NOT READY IN TIME: a 9x9 can take longer than the wait. You then get a job_id instead of a grid -- fetch the grid with geogrid_status, which is free. Calling geogrid_scan again with the same inputs returns that same lookup at 0 credits rather than running a second one, and a finished grid is cached for 24 hours -- but geogrid_status is the way to get the grid.

Collects the grid from a geogrid_scan that returned a job_id instead of a result. FREE -- poll as often as you need.

Returns status "pending" or "running" while the grid is being searched, "complete" with the full grid once done, and "failed" with an error if the scan died (it is refunded). Most scans finish inside geogrid_scan itself and never need this; a scan that runs long is the one that does.

Points that could not be checked have status "error" in grid_points, are counted in failed_points, and are refunded.

READING THE GRID: grid is a 2D array where 0 means the business was not found at that point, not that it ranked zero. average_rank and found_in count only the points where it WAS found, so a strong average_rank across a low found_in means the business ranks well in a small area and is invisible outside it -- which is the finding a geogrid exists to produce.

Use when comparing your business vs local competitors on rankings, reviews, ratings, and Google Business Profile completeness. Returns your_business stats, competitor details with advantages, and your_gaps. Costs 10 credits + 2 per competitor actually returned (default 5 competitors = 20 credits; thin markets may return fewer and cost less).

Use when calculating a composite 0-100 local authority score. Returns authority_score with breakdown by ranking, reviews, profile, and citations (each with score, max, and detail), plus percentile. Good single metric to track over time. Costs 10 credits.

Use when finding the best local keywords to target based on difficulty vs current rank. Returns keywords with estimated_difficulty, your_rank, and search_volume. Costs 4 credits.

Use when you have specific keywords and need monthly volume, CPC, and competition data. Accepts up to 1000 keywords. Returns search_volume, cpc, competition, competition_level, and monthly_searches trend. Volumes are locally scoped when the location is a city/state (volume_scope: "local", data_source: "google_ads"); falls back to country-level numbers when local data is unavailable (volume_scope: "country") — check location_used for the actual scope. If location_alternatives is present, the location has sibling entities (e.g. "Hamilton" vs "Hamilton Township", NJ) whose volumes can differ 3-5x — check them before treating one number as the whole market. A null search_volume means no data, not zero searches. Costs 72 credits.

Use when generating new keyword ideas from a seed keyword. Keyword ideas come from our national keyword database; volumes and CPC are then localized via Google Ads for city/state locations (volume_scope: "local") with a labeled country-level fallback (volume_scope: "country") — check location_used for the actual scope, and location_alternatives for sibling entities like townships. keyword_difficulty remains national (SERP-based). A null search_volume means no data, not zero searches. For metrics on keywords you already have, search_volume returns volume/CPC directly. Costs 92 credits.

Use when you have keywords and want the full picture on them: search volume, CPC and competition PLUS keyword_difficulty and search_intent (informational, navigational, commercial, transactional) and the averaged backlink profile of the pages currently ranking (backlinks, dofollow, referring_pages, referring_domains, referring_main_domains, and the 0-1000 rank and main_domain_rank authority scores) — what it takes to rank for each term. Accepts up to 1000 keywords. IMPORTANT: volumes are country-level (volume_scope: "country") — use search_volume instead when the city/state number is what matters. A null value means no data, not zero. Costs 10-116 credits, by keyword count (10 for one keyword, 20 for a hundred).

Use when expanding a keyword list with semantically related terms. Accepts up to 20 seed keywords. Returns related keywords with search_volume, cpc, competition, and competition_level, sorted by volume. A null search_volume means no data, not zero searches. Costs 72 credits.

Use when reverse-engineering what keywords a competitor domain ranks for. Returns keywords with search_volume, cpc, and competition. IMPORTANT: volumes are country-level (volume_scope: "country") — our keyword database for this tool has no city/state granularity; check location_used for the actual scope. Costs 20 credits.

Use when checking if a keyword is rising, stable, or declining over time. Returns one series per keyword: interest data points (weekly or monthly — see granularity; each point has date), peak_month (null when the keyword has no data), trend_direction, and has_data. The in-progress week/month is left out (partial_period_excluded). IMPORTANT: interest data is country-level (volume_scope: "country") — Google Trends via this source has no city/state granularity; check location_used for the actual scope. Periods: 3m, 6m, 12m (default), 5y. Costs 9 credits.

Use when getting a domain's backlink profile overview. Returns rank, backlinks_total, referring_domains, broken_backlinks, spam_score, and backlinks_by_type. Costs 23 credits.

Use when finding link building opportunities -- sites that link to competitors but not to you. Returns referring domains with domain_authority and which competitors they link to. Costs 23 credits.

Use when auditing a single page's on-page SEO. Returns seo_score, title, meta_description, h1, word_count, load_time_ms, body_text_unreadable, core_web_vitals (lab lcp in ms and cls; inp is null — it needs field data), issues with severity (seo_score is 100 minus 15 per critical, 5 per warning, 1 per info), schema_markup, and mobile_friendly. Costs 1 credit.

Use when finding where a keyword appears in ChatGPT and Google AI outputs. Returns ai_search_volume, total_mentions, and mention details with question, answer_snippet, sources_cited, and platform. IMPORTANT: results are country-level (location_scope: "country") regardless of the location passed — a city resolves to its country and the numbers cover all of it. Check location_used. For city-level AI results use ai_scraper or ai_mode. Costs 88 credits.

Discovers which domains AI models cite most for a topic. Returns top_domains with domain, mentions count, and ai_search_volume. Reports at the domain level; ai_top_pages reports individual pages. IMPORTANT: results are country-level (location_scope: "country") regardless of the location passed — a city resolves to its country and the numbers cover all of it. Check location_used. For city-level AI results use ai_scraper or ai_mode. Costs 81 credits.

Use when finding specific pages (not just domains) that AI models reference most. Returns top_pages with url, domain, mentions, and ai_search_volume. More granular than ai_top_sources. IMPORTANT: results are country-level (location_scope: "country") regardless of the location passed — a city resolves to its country and the numbers cover all of it. Check location_used. For city-level AI results use ai_scraper or ai_mode. Costs 81 credits.

Measures a single domain's overall AI citation score across platforms. Returns total_mentions, total_impressions, ai_search_volume, and platform_breakdown (chat_gpt, google). Covers one domain; ai_compare covers several side by side. IMPORTANT: results are country-level (location_scope: "country") regardless of the location passed — a city resolves to its country and the numbers cover all of it. Check location_used. For city-level AI results use ai_scraper or ai_mode. Costs 81 credits.

Compares 2–5 domains' AI visibility side by side. Returns per-domain total_mentions, total_impressions, and ai_search_volume. For one domain's detailed platform breakdown, see ai_visibility. IMPORTANT: results are country-level (location_scope: "country") regardless of the location passed — a city resolves to its country and the numbers cover all of it. Check location_used. For city-level AI results use ai_scraper or ai_mode. Costs 81 credits per domain compared (2 domains = 162).

Use when measuring how often keywords are searched in ChatGPT and other LLMs. Returns ai_search_volume and monthly trend data per keyword. IMPORTANT: volumes are country-level (volume_scope: "country") regardless of the location passed — check location_used. Costs 9-16 credits, scaling with keyword count (100 keywords = 16).

Gets what a specific LLM says about a query. Returns response_text, the model used, sources with URLs, fan_out_queries, and web_search_used. Each source carries a position — the order it was cited, from 1, counted after duplicate pages collapse. Supports chat_gpt, claude, gemini, perplexity.

WHETHER YOU GET SOURCES depends on whether the model searched the web. perplexity searches on every call, so its sources are populated and it needs no parameters. The other three answer from training data unless you set web_search: true, and on local business questions they otherwise do not search at all.

WEB SEARCH SUPPORT DIFFERS BY PLATFORM. claude takes web_search, force_web_search, search_country and search_city — the full set. chat_gpt takes all four except that GPT-5 models drop force_web_search. gemini takes web_search only: a search can be permitted but never compelled, and it cannot be geographically scoped. perplexity takes search_country only and cannot be switched off. Asking for something a platform does not support returns a 400 saying what it does support.

COST: 8 credits, or 20/40 if model pins a premium/frontier model. With web_search: true it is priced from the measured cost of searching — 24 for chat_gpt, 27 for gemini, 40 for claude. perplexity stays at 8 with search included.

ACCURACY WARNING: without web search a model may state confident, wrong facts about a local business, including that an open business has closed. When checking what a model says about a real business, use a platform that searches: perplexity, or any platform with web_search: true.

MATCHING CITATIONS ON GEMINI: domain is the registrable domain and never the subdomain, because Google's grounding data does not transmit one — a client at orangecounty.example.com is reported as example.com. Match on the registrable domain for subdomain-hosted sites. The other three platforms return the full hostname.

Sampling settings are left at each platform's defaults, which differ and are not all low, so repeating a prompt returns different wording — treat one run as a sample, not a fixed answer.

May take 15-60 seconds; with web_search: true, expect the upper end.

Use when scraping ChatGPT or Gemini search results for a keyword. Returns markdown response, local_businesses, sources, fan_out_queries, and brand_entities. Each entry in sources carries a position — the order it was cited, from 1, after duplicates collapse. Costs 4 credits.

TWO RANKINGS, DO NOT MERGE THEM: local_businesses is the platform's LISTING, in the order it emitted cards. recommended_businesses is the SHORTLIST read out of the answer's own prose, in the order the answer argued for it, with shortlist_rank, listed, mention, is_top_pick and the citation offered beside each entry. listed: true means the entry held a place in a list the answer presented and shortlist_rank is that place; listed: false means the answer named it in a sentence instead, so shortlist_rank is null rather than a position it never had. mention is the answer's own words about the business, plain text — the evidence behind the row. They disagree routinely — ChatGPT opens a local answer by dumping its whole result set and only then writes the list it recommends, so a business the prose puts third can sit tenth in the array. Quote shortlist_rank when a client asks where an AI RECOMMENDS them.

GEMINI HAS NO LISTING AT ALL: it sends no business block, so local_businesses is empty on every gemini local query and recommended_businesses is the only place a business appears. An empty array on gemini is not evidence that nobody was named.

LOCAL BUSINESSES: on a local question, chat_gpt lists businesses inside its answer and we return them as local_businesses — rank, name, category, rating, reviews_count, address, phone, website, domain. Field names it shares with /v1/serp/local-pack mean the same things, so code reading those works against both — but the sets differ: this adds category and domain, and has no cid or hours. gemini has no equivalent and returns an empty array — read recommended_businesses there.

FORCE A SEARCH ON CHAT_GPT: chat_gpt sometimes answers a local prompt with a clarifying question ("which Orange County do you mean?") instead of an answer, which reads as an empty result. force_web_search: true makes it answer, at the same 4 credits, and is what makes the local_businesses block appear reliably. gemini decides for itself and returns a 400 if you ask.

MATCHING CITATIONS ON GEMINI: local answers often cite Google Business Profiles, which arrive with domain "maps.google.com" and the business name in title, identified by the cid in the URL. Match on title or cid rather than domain for those.

search_results is a reserved field we have not observed populated on either platform — read sources. fan_out_queries and brand_entities depend on the query and platform and are often empty.

SLOW: we ask ChatGPT or Gemini the question live and wait for the full answer. May take 30-90 seconds. This is normal, not an error — do not retry a call still in flight, it starts a second billable job.

Use when measuring HOW OFTEN an AI answer names a business, not just whether it did once. Read-only: it asks the same question samples times and reports how often each business appears; nothing is changed or posted anywhere. The runs take one to three minutes, longer than a tool call can wait, so this returns a job_id right away -- call ai_sample_status with it to get the result.

COLLECTING: ai_sample_status is free and the result does not expire. Typical answers are ready in 30-60 seconds and the slowest in about 130 -- wait 30 seconds before the first check and roughly 15 between checks. status is "pending" or "running" until then.

WHY SAMPLE: a model composes its answer per request, so one answer is a sample, not a fact -- ask twice ten minutes apart and the businesses and their order can differ. A client asking "am I showing up in AI answers?" is asking for a rate, which a single ai_scraper or ai_mode call cannot give.

REPEATS: an identical request within 10 minutes returns the run already in progress (deduplicated: true, 0 credits), so retrying after a dropped connection is safe. To measure the same prompt again on purpose, pass force_new: true. Pass idempotency_key to group requests yourself.

PLATFORMS: chat_gpt and gemini cost 4 credits per sample; google_ai_mode costs 2 credits per sample and requires a location. The mention and visibility tools read stored aggregates, so they are not sampleable -- running one ten times returns the same numbers ten times.

COST: samples x the per-run price; 10 samples on chat_gpt is 40 credits. Samples that never complete are refunded, and the final figure is credits_charged on the status response.

Collects the answer to an ai_sample job. FREE — poll as often as you need.

Returns status "pending" or "running" with progress and total_steps while the samples are still going, "complete" with the full distribution once they are done, and "failed" with an error if the job died (a failed job is refunded in full). Typical completion is 30-60 seconds, tail around 130.

WHAT COMES BACK: per business — appearances, appearance_rate, shortlist_rate, mean_rank, mean_shortlist_rank, best_rank, worst_rank, top_pick_count and runs_seen — plus every individual run.

TWO DIFFERENT RANKINGS, DO NOT MERGE THEM. businesses in a run is the platform's LISTING, in the order it emitted cards. recommended_businesses is the SHORTLIST read out of the answer's own prose, in the order the answer argued for it — that is the recommendation, and the two disagree routinely: a business the prose puts third can sit tenth in the listing. Report shortlist_rank when a client asks where an AI recommends them — it is null for a business the answer named in a sentence rather than listed, and those runs are counted in mention_appearances instead of shortlist_appearances. Each entry's mention quotes what the answer actually said. reader_version says which version of that reader produced the shortlist: it is our reading of the answer, not the platform's own listing, so before comparing this job with an older stored one confirm the versions match -- across a bump the numbers are not comparable and a reader improvement reads as a drop. mean_rank and best_rank are listing positions and are null for a business that was never in a listing.

GEMINI HAS NO LISTING AT ALL. It sends no structured business block, so businesses is empty in every gemini run and every gemini figure comes from the prose shortlist. An empty businesses array on gemini is not evidence that nobody was named.

READING THE RATES: every rate is out of samples_returned, which counts only runs that ANSWERED. A failed run and a refusal are both excluded — a run where the model said "I'm having a hard time fulfilling your request" is not a run where the client was absent. Check samples_refused: a high count means the platform is declining the prompt, not that the client is invisible, and per-run outcome says which runs those were. An answer that named nobody IS counted, because that is a real absence. mean_rank averages only the runs that named the business, so a business named 2nd in 3 of 10 runs reads mean_rank 2 and appearance_rate 0.3; do not collapse the two into one score.

cited_domains says which SOURCE the answers cited for each business and in how many runs, most-used first -- an answer sourcing a business from its BBB listing rather than its own site is telling you which page it treats as authoritative, and that is usually the finding a client wants. Note that domain and website on the same row hold a citation too, under names that read as the business's own site.

A business the answers spelled more than one way ("WNY Snow Removal" and "WNY Snow Removal LLC") is reported as ONE row, with every spelling in name_variants -- on gemini there is no cid behind a prose mention, so without that the same business reports two rows at half its real rate each. Only a legal form (LLC, Inc), a bare connector, or a tradeless corporate suffix (Service, Services, Company, Group, Solutions) merges; any word naming a different trade leaves the rows separate, as does a cid. A cited domain separates rows only when it looks like the business's own site -- a directory citation is not evidence of identity. Two rows can still be one business: where one name is the other plus a trade word and both carry the same own-site domain in cited_domains, that is usually one business split across spellings, and its real rate is the two rates added. The split is deliberate -- a chain's branches ("Smith Dental" and "Smith Dental Downtown") share a domain exactly the same way, and nothing in the answer says which case this is. Merging them is yours to decide with context about the business that we do not have; we leave the seam visible rather than guess, because a wrong merge cannot be undone from the payload.

matched_on says how runs were tied together: "cid" is Google's own identifier and is exact, "domain" is domain plus name, "name" is the string alone and is the weakest. Google labels AI Mode cards editorially, so on google_ai_mode prefer the cid.

BILLING: this poll costs nothing, so its credit line reads 0. What the job cost is credits_charged — the submit's reservation less the refund for samples that never completed. Refusals are NOT refunded: the prompt was run and the model answered, it just declined.

Use when deciding whether a business an AI named IS the business you are tracking. Takes the businesses array from ai_scraper, ai_mode or ai_sample plus a target, and returns matched, confidence, matched_on, rank and the near misses.

WHY NOT DO IT YOURSELF: the two obvious rules both fail quietly. Matching on domain misses roughly a third of appearances, because that is how often ChatGPT names a business with an empty website and domain. Matching on name fails on Google AI Mode, which labels cards editorially — the same business came back as "The Classic Staple" in one answer and under its trading name in the next. This matches on cid, then domain, then phone, then name-with-address, then name, and tells you which one it used.

THE TARGET IS RESOLVED FOR YOU: pass business_name and location and the business is looked up in the local graph first, so a name-only target ends up matching on a cid, a domain and a phone rather than on a string. That lookup is what the 5 credits buy. Pass a cid, domain, website or phone yourself and no lookup is made and it costs 1.

ONE ANSWER OR A WHOLE SAMPLE: pass businesses for one answer and get a verdict; pass runs from an ai_sample result and get appearance_rate, best_rank, worst_rank and mean_rank across the sample, with the verdict for each run. Pass one or the other, never both.

READING confidence: 1.0 is a cid, 0.9 a domain or phone, 0.8 a name with a matching address, 0.65 a name alone. matched is true exactly when confidence is 0.5 or above, so a name-only tie between two candidates comes back matched: false — one of them is the client, but nothing in the answer says which. Filter on matched_on when you need identifier-grade certainty.

WHAT IS NOT A SIGNAL: a website on a shared host (Facebook, Instagram, Linktree, business.site, the big directories) is not a domain match. A name matches only when the shorter of the two is wholly contained in the longer, and a one-word name never matches alone. Two addresses agree only when the street number, street line and town all agree. target.place_id needs target.location beside it.

IDENTIFIER COVERAGE — READ THIS BEFORE QUOTING A LOW RATE: identifier_coverage says how much of the answer could be identified AT ALL. identified counts the businesses carrying a cid, a domain or a phone, out of candidates. Two of six means four rows could only ever be matched by name, and a name-only miss is not the same fact as an absence — say so rather than reporting the rate alone. Coverage is a property of what the platform published, not of the client.

WHERE THE CID GOES: pass a cid inside target, where it makes the match exact and skips the lookup. Never filter the businesses you pass in on whether they carry one — the rows without a cid are most of the answer, and dropping them removes the appearances you are trying to count.

SOURCE PROVENANCE, NOT A WARNING: source_graph says which platform's record the AI repeated — google, bing, yelp, aggregator, or unknown. A cid means Google; a Yelp URL means Yelp; a business's own domain means unknown, because it says the AI has the business and not where it read it. entity_variants lists the spellings of the matched business across the runs, each with its source_graph. Two or three variants is the NORMAL state of a business that exists on more than one platform — do not report it as a problem, report it as provenance. It is what lets you say: your Google profile is fine, ChatGPT is reading Bing, and Bing has you in the wrong town.

WHAT IS A PROBLEM: nap_conflicts, and only that. It carries a value that genuinely contradicts the client's own record — a phone number that is not theirs, an address in the wrong town — with the source_graph that supplied it, so the fix has an address. An empty nap_conflicts beside three entity_variants means the client is listed in three places and all three are right.

Use when seeing what Google Ads a competitor domain is running. Returns advertiser, total_ads (after limit), total_available, and per creative: advertiser_name, creative_id, format, first/last shown, and preview_image_url / transparency_url links. Google's Ads Transparency Center does not carry ad headline or body text, landing URLs, or platforms. Costs 2 credits.

Use when monitoring where a brand is mentioned online with sentiment analysis. Returns total_mentions, sentiment_breakdown (positive/neutral/negative), and mention details with domain_authority and sentiment. Costs 23 credits.

Use when resolving city names to the exact format needed by other tools. Call this when a tool returns no results for a location or when the format is ambiguous. Returns name, code, type (location taxonomy: City, County, State, DMA Region, ...), state, country, and parent_code, plus total_count and a truncated flag. IMPORTANT for multi-location ambiguity: many municipalities exist twice (e.g. "Hamilton" AND "Hamilton Township" in NJ — different entities with very different search volumes); pass a bare place name plus the state param to see all of them. Free (0 credits).

Use when diagnosing connection or authentication issues. Tests API connectivity end-to-end by verifying the API key against the backend. Free (0 credits).