AI Answer Sampling

Parameters

Example Request

curl -X POST https://api.localseodata.com/v1/ai/sample \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "best plumber in Orchard Park NY",
    "platform": "chat_gpt",
    "samples": 10
  }'

Example Response

{
  "status": "success",
  "credits_used": 40,
  "data": {
    "job_id": "sample_V1StGXR8Z5",
    "status": "complete",
    "keyword": "best plumber in Orchard Park NY",
    "platform": "chat_gpt",
    "samples_requested": 10,
    "samples_returned": 10,
    "samples_failed": 0,
    "samples_refused": 0,
    "samples_unreadable": 0,
    "samples_shortlist_read": 10,
    "credits_reserved": 40,
    "credits_refunded": 0,
    "credits_charged": 40,
    "reader_version": 5,
    "businesses": [
      {
        "name": "Bolt Plumbing LLC",
        "matched_on": "domain",
        "cid": "",
        "domain": "boltplumbing.com",
        "name_variants": ["Bolt Plumbing", "Bolt Plumbing LLC"],
        "cited_domains": [
          { "domain": "boltplumbing.com", "runs": 5 },
          { "domain": "bbb.org", "runs": 3 }
        ],
        "category": "Plumber",
        "rating": 4.8,
        "reviews_count": 412,
        "address": "1200 Southwestern Blvd, Orchard Park, NY",
        "phone": "+1 716-555-0142",
        "website": "https://boltplumbing.com",
        "appearances": 8,
        "appearance_rate": 0.8,
        "listing_appearances": 8,
        "shortlist_appearances": 7,
        "shortlist_rate": 0.7,
        "mention_appearances": 1,
        "top_pick_count": 2,
        "best_rank": 1,
        "worst_rank": 4,
        "mean_rank": 2.13,
        "best_shortlist_rank": 1,
        "mean_shortlist_rank": 1.86,
        "runs_seen": [1, 2, 3, 5, 6, 8, 9, 10]
      }
    ],
    "runs": [
      {
        "run": 1,
        "ok": true,
        "outcome": "answered",
        "shortlist_read": true,
        "businesses": [],
        "recommended_businesses": [
          {
            "shortlist_rank": 1,
            "listed": true,
            "name": "Bolt Plumbing",
            "mention": "Bolt Plumbing — Orchard Park-based, 24/7 emergency calls.",
            "is_top_pick": false,
            "citation": { "url": "https://boltplumbing.com/", "domain": "boltplumbing.com" }
          }
        ],
        "response_text": "For plumbing in Orchard Park, the names that come up most are..."
      }
    ]
  }
}

Response Fields

Notes

• TWO DIFFERENT RANKINGS, do not merge them. 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 — that is the recommendation, and the two disagree routinely. Report shortlist_rank when a client asks where an AI recommends them.
• 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.
• reader_version says which version of the prose reader produced the shortlist. It is our reading of the answer, not data the platform returned, so before comparing this job against an older stored one confirm the versions match — across a bump the numbers are not comparable and a reader improvement reads as a drop.
• A business the answers spelled more than one way is reported as ONE row, with every spelling in name_variants. Only a legal form (LLC, Inc), a bare connector, or a tradeless corporate suffix merges; any word naming a different trade leaves the rows separate. Two rows can therefore 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, add the two rates. We leave that seam visible rather than guess, because a chain's branches share a domain the same way and a wrong merge cannot be undone from the payload.
• A refusal is not an absence. samples_refused counts runs where the model declined the prompt; those are excluded from every rate, and they are not refunded because the run itself completed.
• appearance_rate is out of samples_returned, not samples_requested. A run that did not complete is a measurement that was not taken, so it is refunded rather than counted as an absence — samples_failed says how many there were.
• mean_rank averages only the runs that named the business. Named 2nd in 3 of 10 runs reads mean_rank 2 and appearance_rate 0.3; the two say different things and which one is bad is the actionable part.
• matched_on says how runs were tied together: "cid" is Google's own identifier and is exact, "domain" is domain plus name (never domain alone — two branches of a chain share one), "name" is the string alone and is the weakest.
• On google_ai_mode prefer the cid. Google labels cards editorially, so the same business can be named differently between runs and a name-keyed count would report it twice at half the rate each.
• Results are never cached. Serving a sample from cache would answer a later question with an earlier answer, which is the failure this endpoint exists to avoid.