# Suggestion

Schemas

Autocomplete suggestions from a platform's search box for a partial query: completed searches, accounts, hashtags and websites, in its order.

## Endpoints

3 endpoints return suggestions on Google Ads Transparency Center, Instagram and TikTok.

- [GETGoogle Ads Transparency Center Search Suggestions API`/v1/google/search_suggestions`](https://socialtap.dev/docs/reference/google/search_suggestions/index.md)
- [GETInstagram Search Suggestions API`/v1/instagram/search_suggestions`](https://socialtap.dev/docs/reference/instagram/search_suggestions/index.md)
- [GETTikTok Search Suggestions API`/v1/tiktok/search_suggestions`](https://socialtap.dev/docs/reference/tiktok/search_suggestions/index.md)

## Schema

Every endpoint above returns an array of these objects as `data`, with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform whose search box offers the suggestion. |
| `text` | `string` | The suggestion as the platform shows it, whitespace-trimmed: the completed search for a query suggestion, the account's name for a profile one, the domain for a website one. |
| `type` | `string` | query = a completed search to run; profile = an account (or community) the platform proposes, described in profile; hashtag = a hashtag, described in hashtag; website = a website the platform proposes: text is its domain (nike.com), as the platform's searches by website take it. New values may be added.<br>One of `query`, `profile`, `hashtag`, `website` |
| `position` | `integer` | Zero-based rank of the suggestion in the list, counting every type: the platform's order (each endpoint's notes say how a list combining several of the platform's searches is ordered). |
| `url` | `string` (uri) | Where the suggestion leads on the platform: the search results page for a query, the account's page for a profile, the hashtag's page for a hashtag, the platform's page for the website for a website. |
| `profile` | `object` or `null` | The account a profile suggestion names; null for every other type. |
| `profile.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `profile.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `profile.display_name` | `string` or `null` | Display name shown on the profile. |
| `profile.url` | `string` (uri) or `null` | Canonical profile URL. |
| `profile.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `profile.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `hashtag` | `object` or `null` | The hashtag a hashtag suggestion names, keyed as the platform's hashtag endpoints key it; null for every other type. |
| `hashtag.id` | `string` | The hashtag's ID as the platform's hashtag endpoints key it: its native ID, or the name lowercased where the platform's pages key a hashtag by name (Instagram). |
| `hashtag.name` | `string` | The tag without #, as the platform shows it (case kept). |
| `hashtag.url` | `string` (uri) | Canonical hashtag page URL. |
| `hashtag.metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `hashtag.metrics.post_count` | `integer` or `null` | Posts carrying the tag, as the platform counts them; rounded on YouTube and Threads (see approximate_fields). |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.tiktok` | `object` or `null` | A TikTok suggestion's own fields. |
| `platform_specific.tiktok.language` | `string` or `null` | The suggestion's language as TikTok labels it, an ISO 639-1 code (en, es); null when TikTok does not say. |
| `platform_specific.tiktok.score` | `number` or `null` | TikTok's predicted click-through rate for the suggestion, 0 to 1: a relative signal among one query's suggestions; null when not given. |
| `platform_specific.instagram` | `object` or `null` | An Instagram suggestion's own fields. |
| `platform_specific.instagram.tag_id` | `string` or `null` | Instagram's own numeric ID of a hashtag suggestion's tag; null for every other type. |
| `platform_specific.google` | `object` or `null` | A Google Ads Transparency Center suggestion's own fields. |
| `platform_specific.google.country_code` | `string` or `null` | The country an advertiser suggestion's advertiser is based in, an ISO 3166-1 alpha-2 code; null for a website suggestion, or when not shown. |
| `platform_specific.google.ads` | `object` or `null` | The ads the center shows for an advertiser suggestion's advertiser, as Google's range (equal bounds when exact), in the region the request names where it takes one; null for a website suggestion, or when not shown. |
| `platform_specific.google.ads.lower_bound` | `integer` | Inclusive lower bound. |
| `platform_specific.google.ads.upper_bound` | `integer` or `null` | Inclusive upper bound; null when open-ended (e.g. ">1M"). Equal to lower_bound when exact. |
| `approximate_fields` | `string[]` | JSON paths of values rounded or capped by the platform (hashtag.metrics.post_count at Instagram's ceiling). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none; \[\] when every list is known (a suggestion has none yet). |

---

[HTML version](https://socialtap.dev/resources/suggestion/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)