Skip to content

Commit 5bafd3d

Browse files
kjellbergkjellberg
committed
Add schema
1 parent 29b3f38 commit 5bafd3d

File tree

1 file changed

+314
-0
lines changed

1 file changed

+314
-0
lines changed

‎serp_response_schema.json‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://github.com/kjellberg/serp_parser/serp_response_schema.json",
4+
"title": "Google SERP Response",
5+
"description": "Full parsed output from SerpParser::Google::Search#to_h",
6+
"type": "object",
7+
"required": [
8+
"ai_overview",
9+
"sponsored_results",
10+
"organic_results",
11+
"faq_results",
12+
"related_searches"
13+
],
14+
"properties": {
15+
16+
"ai_overview": {
17+
"description": "Google AI Overview (formerly SGE). Present only when Google shows an AI-generated answer at the top of the page. null when absent.",
18+
"oneOf": [
19+
{ "type": "null" },
20+
{
21+
"type": "object",
22+
"required": ["answer", "citations"],
23+
"properties": {
24+
"answer": {
25+
"description": "The full AI-generated answer text, including any inline citation link text. null when the answer text was not present in the static HTML (dynamically loaded without scripts).",
26+
"type": ["string", "null"],
27+
"example": "För att få den mest exakta och aktuella väderprognosen för Nykyrka, Motala, rekommenderas att du besöker SMHIs webbplats."
28+
},
29+
"citations": {
30+
"description": "Sources cited inline within the AI answer text, in order of appearance.",
31+
"type": "array",
32+
"items": { "$ref": "#/$defs/ai_citation" }
33+
}
34+
},
35+
"additionalProperties": false
36+
}
37+
]
38+
},
39+
40+
"sponsored_results": {
41+
"description": "Paid/advertised results (Google Ads) shown on the page, in display order.",
42+
"type": "array",
43+
"items": { "$ref": "#/$defs/sponsored_result" }
44+
},
45+
46+
"organic_results": {
47+
"description": "Non-paid search results, in display order. Ad blocks are excluded.",
48+
"type": "array",
49+
"items": { "$ref": "#/$defs/organic_result" }
50+
},
51+
52+
"faq_results": {
53+
"description": "\"People Also Ask\" FAQ accordion items, in display order.",
54+
"type": "array",
55+
"items": { "$ref": "#/$defs/faq_result" }
56+
},
57+
58+
"related_searches": {
59+
"description": "Related search query strings shown at the bottom of the page.",
60+
"type": "array",
61+
"items": {
62+
"type": "string",
63+
"example": "matkasse familj recept"
64+
}
65+
}
66+
67+
},
68+
"additionalProperties": false,
69+
70+
"$defs": {
71+
72+
"ai_citation": {
73+
"description": "A source cited inline in the AI Overview answer text.",
74+
"type": "object",
75+
"required": ["position", "title", "domain", "url"],
76+
"properties": {
77+
"position": {
78+
"description": "1-based position of this citation within the AI answer, in order of appearance.",
79+
"type": "integer",
80+
"minimum": 1,
81+
"example": 1
82+
},
83+
"title": {
84+
"description": "The anchor text of the citation link as it appears in the AI answer.",
85+
"type": ["string", "null"],
86+
"example": "SMHIs webbplats"
87+
},
88+
"domain": {
89+
"description": "Hostname of the cited page, with leading www. stripped.",
90+
"type": ["string", "null"],
91+
"example": "smhi.se"
92+
},
93+
"url": {
94+
"description": "Full URL of the cited page.",
95+
"type": ["string", "null"],
96+
"format": "uri",
97+
"example": "https://www.smhi.se/kunskapsbanken/meteorologi/vaderprognoser/varfor-kan-vaderprognoser-skilja-sig-at"
98+
}
99+
},
100+
"additionalProperties": false
101+
},
102+
103+
"sponsored_result": {
104+
"description": "A single paid/advertised result (Google Ad).",
105+
"type": "object",
106+
"required": ["position", "advertiser", "title", "description", "domain", "url", "site_links"],
107+
"properties": {
108+
"position": {
109+
"description": "1-based position among all sponsored results.",
110+
"type": "integer",
111+
"minimum": 1,
112+
"example": 1
113+
},
114+
"advertiser": {
115+
"description": "The advertiser name displayed above the ad title.",
116+
"type": ["string", "null"],
117+
"example": "Linas Matkasse"
118+
},
119+
"title": {
120+
"description": "The ad headline/title.",
121+
"type": ["string", "null"],
122+
"example": "Linas Matkasse - Prova 2 veckor för 299 kr"
123+
},
124+
"description": {
125+
"description": "The ad body text shown below the title.",
126+
"type": ["string", "null"],
127+
"example": "Välj bland hundratals recept och få maten hemkörd."
128+
},
129+
"domain": {
130+
"description": "Hostname of the ad landing page, with leading www. stripped. All tracking parameters are removed.",
131+
"type": ["string", "null"],
132+
"example": "linasmatkasse.se"
133+
},
134+
"url": {
135+
"description": "Destination URL of the ad. Extracted from Google's aclk redirect. All query parameters (campaign tracking) are stripped — only scheme, host and path are kept.",
136+
"type": ["string", "null"],
137+
"format": "uri",
138+
"example": "https://linasmatkasse.se/kampanj/familj"
139+
},
140+
"site_links": {
141+
"description": "Additional quick-link sitelinks shown beneath the ad.",
142+
"type": "array",
143+
"items": { "$ref": "#/$defs/site_link" }
144+
}
145+
},
146+
"additionalProperties": false
147+
},
148+
149+
"organic_result": {
150+
"description": "A single non-paid search result.",
151+
"type": "object",
152+
"required": ["position", "title", "description", "domain", "url", "date", "rating", "site_links"],
153+
"properties": {
154+
"position": {
155+
"description": "1-based position among all organic results.",
156+
"type": "integer",
157+
"minimum": 1,
158+
"example": 1
159+
},
160+
"title": {
161+
"description": "The result title/headline.",
162+
"type": ["string", "null"],
163+
"example": "Bästa matkassen 2025 – Test av 12 matkassar"
164+
},
165+
"description": {
166+
"description": "The result snippet/description shown below the title.",
167+
"type": ["string", "null"],
168+
"example": "Vi har testat och jämfört de populäraste matkassarna på marknaden."
169+
},
170+
"domain": {
171+
"description": "Hostname of the result URL, with leading www. stripped.",
172+
"type": ["string", "null"],
173+
"example": "bast-i-test.se"
174+
},
175+
"url": {
176+
"description": "Full URL of the result page. Google tracking parameters (gclid, srsltid, utm_*) are stripped.",
177+
"type": ["string", "null"],
178+
"format": "uri",
179+
"example": "https://www.bast-i-test.se/tester_pa_basta/matkass"
180+
},
181+
"date": {
182+
"description": "Publication or last-modified date shown in the snippet, if present.",
183+
"type": ["string", "null"],
184+
"example": "2025-01-15"
185+
},
186+
"rating": {
187+
"description": "Structured rating data extracted from rich snippets. null when no rating is shown.",
188+
"oneOf": [
189+
{ "type": "null" },
190+
{ "$ref": "#/$defs/rating" }
191+
]
192+
},
193+
"site_links": {
194+
"description": "Sitelinks shown beneath the result (featured/expanded layout).",
195+
"type": "array",
196+
"items": { "$ref": "#/$defs/site_link" }
197+
}
198+
},
199+
"additionalProperties": false
200+
},
201+
202+
"faq_result": {
203+
"description": "A single \"People Also Ask\" FAQ item.",
204+
"type": "object",
205+
"required": ["position", "question", "answer", "citations"],
206+
"properties": {
207+
"position": {
208+
"description": "1-based position among all FAQ results.",
209+
"type": "integer",
210+
"minimum": 1,
211+
"example": 1
212+
},
213+
"question": {
214+
"description": "The full question text.",
215+
"type": ["string", "null"],
216+
"example": "Vilken matkasse är bäst i test?"
217+
},
218+
"answer": {
219+
"description": "The expanded answer text. null when the answer was not embedded in the HTML (e.g. scripts were stripped before saving, or the page uses pure client-side lazy loading).",
220+
"type": ["string", "null"],
221+
"example": "Linas Matkasse toppar vår lista 2025 med höga betyg för smak och variation."
222+
},
223+
"citations": {
224+
"description": "Source links shown in the answer card, in display order.",
225+
"type": "array",
226+
"items": { "$ref": "#/$defs/faq_citation" }
227+
}
228+
},
229+
"additionalProperties": false
230+
},
231+
232+
"faq_citation": {
233+
"description": "A source link shown inside a FAQ answer card.",
234+
"type": "object",
235+
"required": ["position", "title", "domain", "url"],
236+
"properties": {
237+
"position": {
238+
"description": "1-based position of this citation within the FAQ answer.",
239+
"type": "integer",
240+
"minimum": 1,
241+
"example": 1
242+
},
243+
"title": {
244+
"description": "The page title of the cited source.",
245+
"type": ["string", "null"],
246+
"example": "Bästa matkassen 2025 – Linas Matkasse"
247+
},
248+
"domain": {
249+
"description": "Hostname of the cited page, with leading www. stripped.",
250+
"type": ["string", "null"],
251+
"example": "bast-i-test.se"
252+
},
253+
"url": {
254+
"description": "Full URL of the cited page.",
255+
"type": ["string", "null"],
256+
"format": "uri",
257+
"example": "https://www.bast-i-test.se/tester_pa_basta/matkass"
258+
}
259+
},
260+
"additionalProperties": false
261+
},
262+
263+
"site_link": {
264+
"description": "A sitelink shown beneath an organic result or ad.",
265+
"type": "object",
266+
"required": ["position", "title", "url"],
267+
"properties": {
268+
"position": {
269+
"description": "1-based position within the sitelinks list for this result.",
270+
"type": "integer",
271+
"minimum": 1,
272+
"example": 1
273+
},
274+
"title": {
275+
"description": "The sitelink anchor text.",
276+
"type": ["string", "null"],
277+
"example": "Meny denna vecka"
278+
},
279+
"url": {
280+
"description": "Full URL of the sitelink destination.",
281+
"type": ["string", "null"],
282+
"format": "uri",
283+
"example": "https://linasmatkasse.se/meny"
284+
}
285+
},
286+
"additionalProperties": false
287+
},
288+
289+
"rating": {
290+
"description": "Rich-snippet rating data extracted from an organic result.",
291+
"type": "object",
292+
"required": ["max_score"],
293+
"properties": {
294+
"score": {
295+
"description": "The numeric rating score.",
296+
"type": ["number", "null"],
297+
"example": 4.5
298+
},
299+
"max_score": {
300+
"description": "The maximum possible score (always 5 unless the snippet states otherwise).",
301+
"type": "number",
302+
"example": 5
303+
},
304+
"number_of_ratings": {
305+
"description": "How many ratings the score is based on.",
306+
"type": ["integer", "null"],
307+
"example": 312
308+
}
309+
},
310+
"additionalProperties": false
311+
}
312+
313+
}
314+
}

0 commit comments

Comments
 (0)