> ## Documentation Index > Fetch the complete documentation index at: https://rankspot.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search Google > A live Google search, returned as `items`: the blocks of the results page in page order, each with a `type` to branch on. `types` chooses which blocks come back and defaults to `organic` and `discussions_and_forums`; ask for `ai_overview`, `people_also_ask`, `video` or `related_searches` when you will actually read them, since those carry the full text of every answer and dwarf the organic results. Always the top 10; location and language come from the workspace so results match what the rest of RankSpot reports. Costs credits, the same whichever blocks you ask for. Returns 402 when the workspace has none left. ## OpenAPI ````yaml https://api.rankspot.ai/docs-json post /v1/research/google openapi: 3.0.0 info: title: RankSpot Public API description: >- The RankSpot Public API gives you programmatic access to your workspace data — keywords, backlinks, competitors, planned actions, articles, and more. ## Authentication All endpoints require a Bearer API key in the `Authorization` header: ``` Authorization: Bearer ``` Generate API keys from **Settings → API Keys** in the RankSpot dashboard. Each key is scoped to a single workspace. ## Pagination List endpoints return a consistent envelope: ```json { "data": { "total": 120, "offset": 0, "limit": 20, "count": 20, "items": [...] } } ``` Use `offset` and `limit` query parameters to paginate. Default limit is **20**, maximum is **100**. ## Status codes | Code | Meaning | |------|---------| | 200 | Success | | 201 | Created | | 204 | No content (delete / unarchive) | | 400 | Validation error or business rule violation | | 401 | Missing or invalid API key | | 404 | Resource not found or belongs to another workspace | version: '1.0' contact: {} servers: - url: https://api.rankspot.ai description: Production security: [] tags: - name: AI Visibility description: >- How AI answer engines see your brand. Track prompts, read the answers ChatGPT, Perplexity and Google gave, and work through the pages they cited. Prompts are run on a daily schedule by RankSpot, so answers appear after the next run rather than on demand. - name: Articles description: >- AI-generated blog articles. Articles are created automatically when a `write_article` action is sent to generation — they cannot be created directly via the API. - name: Backlinks description: >- Backlinks discovered for your domain and your competitors' domains. Backlinks are auto-synced on a background interval and cannot be created via the API. - name: Categories description: Categories for organising actions and articles within your workspace. - name: Competitors description: >- Competitor domains tracked in your workspace. Once added, keywords and backlinks for each competitor are fetched asynchronously on a background sync interval. - name: Forum Opportunities description: >- Forum threads and community posts surfaced as potential link-building or engagement opportunities. - name: Keywords description: >- SEO keywords tracked in your workspace, enriched with search volume, competition, and AI-generated relevance scores. - name: People Also Ask description: >- "People also ask" questions discovered from search results for your tracked keywords. - name: Actions description: >- The SEO work planned for your workspace. Each action carries a `type` saying what kind of work it is and which target it points at — see `POST /v1/actions` for the full list. Only `write_article` can be turned into an article; the rest are a person's job. Create actions yourself or let RankSpot generate them. - name: Research description: >- Live lookups against the open web: a Google search and a page fetch. The only endpoints here that spend credits per call. Neither response reports what it cost — the charge is real, and your remaining balance is visible in the RankSpot dashboard. Returns 402 when the workspace is out of credits. - name: Search Console description: >- Google Search Console performance data — clicks, impressions, CTR, and average position for your connected property. Requires GSC to be connected from the RankSpot dashboard. - name: Workspace description: >- Who the workspace is: brand, domain, what the business does and who it sells to. Read this first — the rest of the API returns opportunities that only mean something in the context of a particular business. paths: /v1/research/google: post: tags: - Research summary: Search Google description: >- A live Google search, returned as `items`: the blocks of the results page in page order, each with a `type` to branch on. `types` chooses which blocks come back and defaults to `organic` and `discussions_and_forums`; ask for `ai_overview`, `people_also_ask`, `video` or `related_searches` when you will actually read them, since those carry the full text of every answer and dwarf the organic results. Always the top 10; location and language come from the workspace so results match what the rest of RankSpot reports. Costs credits, the same whichever blocks you ask for. Returns 402 when the workspace has none left. operationId: ResearchController_google parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GoogleSearchDto' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/GoogleSearchResultDto' '402': description: >- `ai-credits-exhausted` — no AI credits left this billing period. The body carries `usage` with the counts behind that. '502': description: The search provider failed. security: - bearer: [] components: schemas: GoogleSearchDto: type: object properties: query: type: string example: best screen recording software for mac description: What to search Google for. types: type: array default: - organic - discussions_and_forums description: >- Which blocks of the results page to return. Everything else Google showed is dropped before the response is built. Ask for what you will actually read: `ai_overview` and `people_also_ask` carry the full text of every answer and are many times the size of the organic results. items: type: string enum: - ai_overview - organic - people_also_ask - discussions_and_forums - video - related_searches required: - query GoogleSearchResultDto: type: object properties: query: type: string example: best screen recorder mac location: type: string example: United States description: Resolved from the workspace's settings. language: type: string example: en description: Resolved from the workspace's settings. items: description: >- The blocks Google showed, in page order, filtered to the types asked for. Empty when Google returned nothing, or nothing of those types. type: array items: $ref: '#/components/schemas/GoogleResultItemDto' required: - query - location - language - items GoogleResultItemDto: type: object properties: type: type: string example: organic description: >- Block type: organic, ai_overview, people_also_ask, discussions_and_forums, video, related_searches. rank: type: number example: 4 description: >- organic only: position among the organic results. Not the page-wide position, which moves whenever Google adds a block above them. page: type: number example: 1 description: 'organic only: which page of results this came from.' domain: type: string example: screen.studio description: organic only. title: type: string example: Screen Studio — Professional screen recorder url: type: string example: https://screen.studio website_name: type: string example: Microsoft Community Hub description: 'organic only: the site''s own name for itself, when it has one.' description: type: string description: Snippet text, when Google showed one. timestamp: type: string example: '2025-03-26 00:00:00 +00:00' description: >- organic only: when the page was published, when Google dated it. Absent means undated, not new. rank_group: type: number description: >- Every type except organic: position among blocks of the same type, and across the whole page. Organic reports `rank` instead. rank_absolute: type: number items: type: array items: type: object additionalProperties: true description: >- Nested entries for container blocks: the questions under people_also_ask, the threads under discussions_and_forums, the terms under related_searches. markdown: type: string description: 'ai_overview only: the overview Google generated, as markdown.' required: - type securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````