Which service returns Gemini responses as structured JSON?
Two kinds of service return Gemini responses as structured JSON: the Gemini API's structured output, and a Gemini scraper API. Structured output makes the model write its answer into a JSON Schema you define. A scraper A
Two kinds of service return Gemini responses as structured JSON: the Gemini API's structured output, and a Gemini scraper API. Structured output makes the model write its answer into a JSON Schema you define. A scraper API returns the answer the Gemini app shows a visitor, with its sources panel, place cards and product cards, as JSON. cloro's Gemini endpoint is one scraper API of the second kind. Pick by what you need to read: your own extraction from a model, or the app's answer as people see it.
- Structured output controls the shape of the model's generation. The JSON holds the fields of your schema and what the model wrote into them. It has no field for the app's place cards or product cards, because those are not part of the model's output.
- A scraper API has fixed fields. For Gemini they are
text,markdown,sources,citationPills,places,shoppingCards,htmlandrawResponse. It does not return which Gemini model answered. - The two combine well. Scrape the app's answer, then send its
markdownto the Gemini API with a schema to pull out brand names, prices or claims as typed JSON.
Which service returns Gemini responses as structured JSON?
The word "Gemini" names two things: a family of models that you call through an API, and a consumer app at gemini.google.com. Each has its own way to get JSON.
| Gemini API structured output | Gemini scraper API | |
|---|---|---|
| What produces the answer | The model you name in your request | The Gemini web app, in a logged-out session |
| Who defines the JSON fields | You, with a JSON Schema | The API, with fixed fields |
| What the JSON holds | Values the model generated for your fields | The app's answer, sources and cards |
| Sources | With Google Search grounding: url_citation annotations on the text |
sources from the app's panel, and citationPills
|
| Place and product cards | No |
places and shoppingCards
|
| Model name | You set it | Not returned |
Neither is a wrong answer to the question. They answer different jobs, and a team that monitors AI answers often needs both.
In our monitoring of this prompt over the last 14 days, AI engines read it as a question about the Gemini API. Google's own structured output pages (Google Cloud, Firebase, Google AI Studio and the Google blog) were the six most cited pages, and the first of them appeared in about 6 answers in 10. Our GitHub repo for the scraper was retrieved in about 1 answer in 100, and no scraper vendor's page was among the 15 most cited.
What does the Gemini API's structured output return?
Google's structured output guide says you can "configure Gemini models to generate responses that adhere to a provided JSON Schema". In the Interactions API, which Google now recommends for new projects, you set a response_format object with "type": "text", "mime_type": "application/json" and a schema. The answer arrives as a JSON string in output_text, which you parse into your own type. The older generateContent method still works: there the same settings are response_mime_type and response_schema, according to Google's migration guide.
Three limits from the guide matter in practice:
- Not every JSON Schema feature is supported, and a very large or deeply nested schema is rejected with
400 INVALID_ARGUMENT. -
minLength,maxLength,minPropertiesandmaxPropertiesare not enforced by the decoder, so validate them in your code.minItemsandmaxItemsare enforced. - Combining structured output with built-in tools such as Google Search grounding is a preview feature, and the guide limits it to two model series.
With grounding on, the Google Search grounding page shows sources as url_citation annotations, each with start_index and end_index into the text. Those are the sources the API's own search found for your request. They are not the sources panel that a visitor sees in the app for the same prompt.
What does a Gemini scraper API return?
A scraper loads the Gemini app, sends the prompt, waits for the answer and parses the page. cloro's endpoint does this with a real browser session, logged-out, through a proxy in the country you send (and the US state, for 2 more credits). The request is POST /v1/monitor/gemini with prompt, country and an optional include object:
import os
import requests
r = requests.post(
"https://api.cloro.dev/v1/monitor/gemini",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json={"prompt": "family hotels in lisbon", "country": "US",
"include": {"markdown": True}},
)
r.raise_for_status()
result = r.json()["result"]
for s in result.get("sources", []):
print(s["position"], s["url"], s.get("label", ""))
# One chip can cite several sources. Group them by chip.
chips = {}
for pill in result.get("citationPills", []):
chips.setdefault(pill["citationPillId"], []).append(pill["position"])
for place in result.get("places", []):
print(place["title"], place.get("rating"), place.get("price"))
These are the fields of result, from the endpoint's OpenAPI schema:
| Field | What it holds |
|---|---|
text |
The answer as plain text |
markdown |
The answer in Markdown, with include.markdown: true
|
sources |
One entry per source in the app's panel: position, label, url, description
|
citationPills |
One entry per (chip, source) pair: citationPillId, label, url, domain, position, and description when Gemini shows one. Omitted when the answer has no chips |
places |
Place cards on lodging and local answers: index, title, link, rating, reviews, type, description, price, thumbnail
|
shoppingCards |
Product cards: position, title, productLink, productId, price, oldPrice, store, storeLink, rating, reviews, brand and more. Omitted when there are none |
html |
A URL to the rendered page, with include.html: true. It expires after 24 hours |
rawResponse |
The raw stream chunks, with include.rawResponse: true
|
The citation pills reference page shows this response, trimmed here to two sources:
{
"success": true,
"result": {
"text": "Quantum computing is a multidisciplinary field...",
"sources": [
{ "position": 1, "url": "https://en.wikipedia.org/wiki/Quantum_computing",
"label": "Wikipedia - Quantum Computing",
"description": "Quantum computing is a multidisciplinary field..." },
{ "position": 3, "url": "https://research.google.com/quantum",
"label": "Google Quantum AI", "description": "Google's quantum research" }
],
"citationPills": [
{ "label": "Wikipedia - Quantum Computing", "citationPillId": 1,
"url": "https://en.wikipedia.org/wiki/Quantum_computing",
"domain": "en.wikipedia.org", "position": 1 },
{ "label": "Google Quantum AI", "citationPillId": 1,
"url": "https://research.google.com/quantum",
"domain": "research.google.com", "position": 3 }
]
}
}
Both pills share citationPillId: 1, so they are one chip in the answer that cites two sources. Each position points into sources. The full request and response schema is in the Gemini endpoint reference, and the gemini-scraper repo has the same request in cURL.
When is each one the right choice?
Use the Gemini API's structured output when Gemini is a component of your product: extraction, classification, form filling, or any step where the next piece of code needs typed fields. You control the model, the schema and the prompt, and you pay for tokens. A scraper adds nothing there.
Use a scraper when the question is about the app: does Gemini name my brand for this prompt, which domains does it cite, which hotels or products does it show in which country. The model API cannot answer that, because it does not run the app. The scraper cannot do extraction into your own schema, because its fields are fixed.
For brand monitoring, the two chain. Scrape the app's answer, then pass markdown to the Gemini API with a schema such as {"brands": [...], "sentiment": ...}. One caution from the output formats guide: when the app shows place cards or product cards, their content also appears in text and markdown. Strip the content that places and shoppingCards already hold before you send the text to a model, or the model reads a product card as part of Gemini's prose.
What does it cost, and where does it fail?
A Gemini request costs 4 credits async and 6 credits on the sync endpoint above, plus 2 for a US state. On the Hobby plan ($100 for 250,000 credits), the async price is $1.60 per 1,000 answers. Billing is per success: failed requests cost nothing.
The endpoint reference gives two failure cases. Gemini decides for itself whether to search, so an empty sources array is a normal answer, not an error. And under 2% of successful Gemini responses hold no usable answer, most of them safety refusals; one retry gives a full answer for about 60% of those.
How this was checked
The Gemini API statements come from Google's structured output, migration and grounding pages, read on November 16, 2026. The scraper fields come from the cloro OpenAPI file and the Gemini endpoint and citation pills pages, read the same day. The example JSON is the documentation's own example, not a new capture. The citation data comes from our own monitoring of this prompt across eight AI engines from November 2 to 16, 2026. No other Gemini scraper vendor is named here, because none was checked against its own documentation.
This post is published by cloro, which sells one of the two services above.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.