General
The HyperSuggest API allows you to access the tools of HyperSuggest through a programmable HTTP interface. Access to the API is not included by default in the subscription bundles available for HyperSuggest. You will need to submit an individual request here in order to access the API.
Core concept
HyperSuggest provides tools for keyword research and some of the tasks that are run under the hood can potentially take more than 1 minute to complete. In order to provide a highly available service, the API utilizes the concept of job scheduling and job polling instead of providing the data in realtime (which would mean your API client would have to wait for a potentially long time before receiving a response).
As an API user, you schedule jobs that describe which HyperSuggest tool should be run with a given set of parameters. You’ll receive an identifier for a scheduled job that you can use to periodically query the API for the current job status and job results.
Rate limits
Access to the API is rate limited. Rate limits are calculated on an account basis, meaning all requests made with your API keys are counted towards the limit regardless of client IP.
Different endpoints of the API have individual rate limits based on their intended usage. For example, you are allowed to schedule a certain number of jobs per minute, but the endpoint used to poll the job status has a much more generous limit, given that you may need to query multiple job status simultaneously.
API responses will additionally include the X-Ratelimit-Limit
, X-Ratelimit-Remaining
and X-Ratelimit-Reset
headers which you can use to make sure you are not triggering rate limits by accident.
The actual rate limit values are included in the documentation for each endpoint below.
Quotas
Access to the API is limited by quotas. Quotas refer to the amount of jobs you are allowed to schedule in a given timespan. As an example, if you’re subscribed to a bundle that includes 1.000/mo API access, you are entitled to schedule 1.000 jobs in a single month. Requests for polling job status and failed jobs do not count towards that limit.
You can use the GET /account/access endpoint to receive detailed information about your accounts current quotas.
API model
Tools
On a programmatic level, the HyperSuggest service is described by and divided into the following tools:
suggest/amazon
A tool for finding search suggests on Amazon.suggest/ebay
A tool for finding search suggests on Ebay.suggest/google
A tool for finding search suggests on the standard Google search.suggest/images
A tool for finding search suggests on Google Images.suggest/instagram
A tool for finding search suggests for hashtags on Instagram.suggest/news
A tool for finding search suggests on Google News.suggest/pinterest
A tool for finding search suggests for pins and user profiles on Pinterest.suggest/shopping
A tool for finding search suggests on Google Shopping.suggest/youtube
A tool for finding search suggests on YouTube.wh/google
A tool for finding WH question suggests on the standard Google search.metrics/google
A tool for finding detailed Google SEO data for a set of keywords.clustering
A tool for AI-powered clustering of a set of keywords by topic.
In code examples below, the TOOL
placeholder can be replaced with any feature paths.
Exhaustive list of tools
suggest/amazon
suggest/ebay
suggest/google
suggest/images
suggest/instagram
suggest/news
suggest/pinterest
suggest/shopping
suggest/youtube
wh/google
metrics/google
clustering
Special case: suggest/google
If your account has access to both the suggest/google
and metrics/google
tools, every suggest/google
job will automatically attempt to retreive detailed metrics for the keywords found while performing the suggest lookup. This means that jobs scheduled with the suggest/google
tool will use up quota for metrics/google
if possible. A suggest/google
job will run just fine if your account does not have access or no quota left for metrics/google
, but detailed metrics will be missing in the job results.
The permit
field included in job status information indicates if a given suggest/google
job has queried detailed metrics. If the permit
array includes the metrics/google
value, detailed metrics have been queried, otherwise not.
Feature paths
Feature paths are used to describe access rights and quotas for individual HyperSuggest tools and features.
In the API, they are primarily used to transparently communicate what features your API user account can access and how much of your bundle quota is left via the GET /account/access endpoint.
In code examples below, the FEATURE_PATH
placeholder can be replaced with any of the following values:
Exhaustive list of feature paths
suggest/amazon
suggest/ebay
suggest/google
suggest/images
suggest/instagram
suggest/news
suggest/pinterest
suggest/shopping
suggest/youtube
wh/google
metrics/google
clustering
api
Data formats
The API communicates via HTTP and uses JSON payloads.
number
fields are represented as actual numbers in request / response JSON payloads. Numbers are never encoded as strings ("4.6"
).boolean
fields are represented as actual booleans in request / response JSON payloads. Booleans are never encoded as string ("true"
,"false"
) or number values (0
,1
).Date
fields are represented as simplified extended ISO 8601 formatted strings, in terms of UTC+0. Example:"2022-02-08T10:30:15.000Z"
.
Request format
GET
requests accept parameters as URL parameters.POST
requests accept parameters in a JSON-encoded request body (Content-Type:application/json
).
Response format
-
Response payloads have a content type of
application/json; charset=utf-8
. TheContent-Type
HTTP header is set accordingly. -
Response payloads are in
JSON
format with keys following thesnake_case
naming convention. -
Response payloads have one of the following two base structures, depending on whether the request failed or succeeded:
Success
// HTTP StatusCode: 200 { "status": "success", "data": {...} | [...] | null // The response data for the given endpoint. If the endpoint does not return data and simply acknowledges the successful processing of the request, this field is set to `null`. }Error
{ "status": "error", "error_code": string, // A distinct error code indicating the type of error that occurred. Each endpoint description below contains a respective list of possible values for this field. "message"?: string | string[] // Optionally and if applicable, a human readable, detailed explanation of why the error occurred (US locale, only). }The HTTP StatusCode is also set to represent the error (see
error_code
details in the endpoint documentation). However, sinceerror_code
values generally describe the issue that occurred more accurately, we advise you to rely on them to handle error responses.
Payload compression
The API supports gzip
compression of response payloads. After profiling the API extensively for the past months, we have decided to make adoption of gzip
compression mandatory for all API users. Since we’re potentially querying data for thousands of keyword combinations, data for some job configurations can get quite big (multiple MBs uncompressed). In oder to ensure the service is running smoothly in the future, we need to keep data throughput at a sane level.
To enable gzip
compression, add the Accept-Encoding: gzip
header to your requests and use a gzip
compatible client to run the query. Here is a list of tools and open source HTTP clients that support gzip
by default:
- Postman
- axios, got, node-fetch (node.js)
- urllib3 (python)
If you’re using one of these to access the API, you shouldn’t have to worry about enabling compression at all.
Authentication
API endpoints are authenticated by providing a valid api key in the X-HyperSuggest-ApiKey
request header field.
If you are subscribed to a version of HyperSuggest that includes API access, you can find your API key in the account page of the HyperSuggest dashboard.
Common error codes
-
bad_request :400
The request payload or one of the payload fields was either badly formatted or is missing.If request payload fields were missing or badly formatted, the
message
response field will contain detailed information for each payload field. Additionally,invalid_fields
will contain a list of invalid payload field names causing the error to occur.Example
// HTTP StatusCode: 400 { "status": "error", "error_code": "bad_request", "message": [ "tool must be one of the following values: suggest/amazon, suggest/ebay, suggest/google, suggest/images, suggest/instagram, suggest/news, suggest/pinterest, suggest/shopping, suggest/youtube, wh/google, metrics/google, clustering" ], "invalid_fields": [ "tool" ] } -
unauthorized :401
TheX-HyperSuggest-ApiKey
header is missing or the API Key you have provided is invalid. -
forbidden :403
The api key provided is not entitled to access the requested resource. -
not_found :404
The requested resource does not exist. -
gzip_required :406
TheAccept-Encoding
HTTP header is missing thegzip
option. More info. -
rate_limit_exceeded :429
You have made too many requests to this endpoint and the rate limit is in effect. TheRetry-After
HTTP header indicates how many seconds to wait before making a follow-up request. -
internal_server_error :500
The request could not be processed for an unknown reason. It is probably best to indicate to your users to retry the request after a few minutes.
Quick start
- If you are subscribed to a version of HyperSuggest that includes API access, find your API key in the account page of the HyperSuggest dashboard.
- Try the request below to fetch information about your account’s access status.
curl -X GET \
-H "X-HyperSuggest-ApiKey: YOUR_API_KEY" \
--compressed \
https://api.hypersuggest.com/account/access
-
You should see a response describing your account’s current access and quota status similar to the example here.
-
(Optional) We have prepared a Postman collection ready for you to explore and use as a starting point for your integration of the HyperSuggest API. The collection includes all endpoints and example payloads. Remember to set the
api_key
variable in Postman to your own API key.
Endpoints
GET /account/access
This endpoint is used to fetch information about your account’s current access and quota status.
Rate limit
This endpoint is rate limited to 1 request every 5 seconds, calculated as 12 requests / minute.
Parameters
This endpoint has no parameters.
Success data
{
"access": {
FEATURE_PATH: {
"grant": boolean, // `false` means no access, `true` means access granted.
"result_limit": number | null, // If set, results will be limited to that amount, because your subscription does not include access to all results for this feature.
"quota": { // If set, access to this feature is limited by a quota. If unset, your account has unlimited access to this feature.
"value": number, // The amount left. This value will decrement with every job you schedule that uses this feature.
"next_replenishment": Date | null // The point in time when quotas for this feature will replenish (typically the start of the next month). If `null`, the quotas will never replenish (one-off).
} | null
}
}
},
Example
// HTTP StatusCode: 200
{
"status": "success",
"data": {
"access": {
"suggest/google": {
"grant": true,
"result_limit": null,
"quota": null
},
"suggest/images": {
"grant": true,
"result_limit": null,
"quota": null
},
"suggest/amazon": {
"grant": true,
"result_limit": null,
"quota": null
},
"suggest/ebay": {
"grant": true,
"result_limit": null,
"quota": null
},
"suggest/shopping": {
"grant": true,
"result_limit": null,
"quota": null
},
"suggest/youtube": {
"grant": true,
"result_limit": null,
"quota": null
},
"suggest/instagram": {
"grant": false,
"result_limit": null,
"quota": null
},
"suggest/news": {
"grant": true,
"result_limit": null,
"quota": null
},
"suggest/pinterest": {
"grant": true,
"result_limit": null,
"quota": null
},
"suggest/wh/google": {
"grant": true,
"result_limit": 15,
"quota": null
},
"metrics/google": {
"grant": true,
"result_limit": null,
"quota": {
"value": 500,
"next_replenishment": "2022-02-01T00:00:00.000Z"
}
},
"clustering": {
"grant": true,
"result_limit": null,
"quota": {
"value": 1000,
"next_replenishment": null
}
},
"api": {
"grant": true,
"result_limit": null,
"quota": {
"value": 192,
"next_replenishment": "2022-02-01T00:00:00.000Z"
}
}
}
}
}
Scheduling jobs
Scheduling jobs is done by posting to one of the tool endpoints listed below. Every tool is associated with an API route starting with /jobs/
followed by the tool identifier.
Common
All job scheduling endpoints share the following criteria:
Rate limit
Job scheduling endpoints are rate limited to 1 request every 2 seconds, calculated as 30 requests / minute. The rate limit is calculated and summarized across all job scheduling endpoints.
Success data
{
"job_id": string // The id of the job that was created. Use this id to query job results.
}
Example
// HTTP StatusCode: 201
{
"status": "success",
"data": {
"job_id": "62038acb0ba10f58445db94c"
}
}
Error codes
-
insufficient_permit :403
The job could not be created because a quota is depleted or you are not allowed to access this resource. Themessage
response field will contain detailed information about what features couldn’t be accessed.Example
// HTTP StatusCode: 403 { "status": "error", "error_code": "insufficient_permit", "message": "Features with insufficient permit: suggest/google." }
POST /jobs/suggest/google
This endpoint is used to schedule a job running the suggest/google
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"country_code": string, // The country in which to perform the suggest queries.
"language_code": string // The language in which to perform the suggest queries.
}
Please refer to the /meta/suggest/google endpoint for a list of valid values and combinations for country_code
and language_code
.
POST /jobs/suggest/images
This endpoint is used to schedule a job running the suggest/images
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"country_code": string, // The country in which to perform the suggest queries.
"language_code": string // The language in which to perform the suggest queries.
}
Please refer to the /meta/suggest/images endpoint for a list of valid values and combinations for country_code
and language_code
.
POST /jobs/suggest/news
This endpoint is used to schedule a job running the suggest/news
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"country_code": string, // The country in which to perform the suggest queries.
"language_code": string // The language in which to perform the suggest queries.
}
Please refer to the /meta/suggest/news endpoint for a list of valid values and combinations for country_code
and language_code
.
POST /jobs/suggest/shopping
This endpoint is used to schedule a job running the suggest/shopping
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"country_code": string, // The country in which to perform the suggest queries.
"language_code": string // The language in which to perform the suggest queries.
}
Please refer to the /meta/suggest/shopping endpoint for a list of valid values and combinations for country_code
and language_code
.
POST /jobs/suggest/youtube
This endpoint is used to schedule a job running the suggest/youtube
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"country_code": string, // The country in which to perform the suggest queries.
"language_code": string // The language in which to perform the suggest queries.
}
Please refer to the /meta/suggest/youtube endpoint for a list of valid values and combinations for country_code
and language_code
.
POST /jobs/suggest/amazon
This endpoint is used to schedule a job running the suggest/amazon
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"marketplace": string, // The marketplace in which to perform the suggest queries.
"category": string // The category in which to perform the suggest queries.
}
Please refer to the /meta/suggest/amazon endpoint for a list of valid values and combinations for marketplace
and category
.
POST /jobs/suggest/ebay
This endpoint is used to schedule a job running the suggest/ebay
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"shop": string, // The shop in which to perform the suggest queries.
}
Please refer to the /meta/suggest/ebay endpoint for a list of valid values for shop
.
POST /jobs/suggest/instagram
This endpoint is used to schedule a job running the suggest/instagram
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"country_code": string, // The country in which to perform the suggest queries.
}
Please refer to the /meta/suggest/instagram endpoint for a list of valid values for country_code
.
POST /jobs/suggest/pinterest
This endpoint is used to schedule a job running the suggest/pinterest
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"country_code": string, // The country in which to perform the suggest queries.
}
Please refer to the /meta/suggest/pinterest endpoint for a list of valid values for country_code
.
POST /jobs/wh/google
This endpoint is used to schedule a job running the wh/google
tool.
Parameters
{
"keyword": string, // The keyword to be used as the base for suggest queries. Max. 100 characters.
"country_code": string, // The country in which to perform the suggest queries.
"language_code": string, // The language in which to perform the suggest queries.
"prefixes": string[] // The wh question prefixes used to extend the keyword in suggest queries. Max. 7 items, 100 characters each.
}
Please refer to the /meta/wh/google endpoint for a list of valid values for country_code
.
POST /jobs/metrics/google
This endpoint is used to schedule a job running the metrics/google
tool.
Parameters
{
"keywords": string[], // The keywords for which to lookup detailed SEO metrics. Max. 500 items, 80 characters each.
"country_code": string, // The country for which to lookup the metrics.
"language_code": string, // The language for which to lookup the metrics.
}
Please refer to the /meta/metrics/google endpoint for a list of valid values and combinations for country_code
and language_code
.
POST /jobs/clustering
This endpoint is used to schedule a job running the clustering
tool.
Parameters
{
"keywords": string[], // The keywords for which to run the clustering. Max. 1000 items, 100 characters each.
}
Querying job data
Querying job data is done by sending a GET request to /jobs/:id
where :id
is the id you receive when scheduling a job.
GET /jobs/:id
This endpoint is used to retreive the status and results of a given job.
Rate limit
This endpoint is rate limited to 1 request every 0.5 seconds, calculated as 120 requests / minute.
Parameters
This endpoint has no parameters.
Success data
This endpoint returns status information and – if the job succeeded – the full results of a given job.
The status information is the same for all jobs, regardless of the tool they run:
{
"id": string, // The id of the job.
"created_at": Date, // The timestamp of when the job was scheduled.
"parameters": {...}, // The parameters used when scheduling the job.
"permit": string[], // A list of FEATURE_PATH identifiers, indicating what features the job is using.
"status": "processing" | "failed" | "succeeded"
}
Depending on the value of the status
field, the response will include additional data:
-
processing
Indicates that the job is currently being processed.{ "progress": number // A value between 0 and 1 indicating how far the job as progressed. } -
failed
Indicates that the job has failed processing. Quotas will not be charged for failed jobs.// No additional data. -
succeeded
Indicates that the job has finished successfully.{ "results": {...} // The job results (see below). }
Job result data per tool
suggest/google
Please refer to this section to learn about why the metrics
field is potentially null
.
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
"metrics": {
"search_volume": number | null,
"competition": number | null,
"cpc": number | null,
"categories": number[],
"keyword_difficulty": number | null,
"daily_impressions_average": number | null,
"serp_item_types": string[],
"monthly_searches": {
"year": number,
"month": number,
"search_volume": number
}[]
} | null
}[]
}
}
suggest/images
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
}[]
}
}
suggest/news
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
}[]
}
}
suggest/shopping
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
}[]
}
}
suggest/youtube
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
}[]
}
}
suggest/amazon
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
}[]
}
}
suggest/ebay
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
}[]
}
}
suggest/instagram
{
"meta": {
"hashtag_count": number
},
"data": {
"hashtags": {
"hashtag": string,
"media_count": number
}[]
}
}
suggest/pinterest
{
"meta": {
"query_count": number,
"user_count": number
},
"data": {
"queries": {
"keyword": string
}[],
"users": {
"name": string,
"url": string
}[]
}
}
wh/google
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
}[]
}
}
metrics/google
{
"meta": {
"keyword_count": number
},
"data": {
"keywords": {
"keyword": string,
"metrics": {
"search_volume": number | null,
"competition": number | null,
"cpc": number | null,
"categories": number[],
"keyword_difficulty": number | null,
"daily_impressions_average": number | null,
"serp_item_types": string[],
"monthly_searches": {
"year": number,
"month": number,
"search_volume": number
}[]
} | null
}[]
}
}
clustering
{
"meta": {
"cluster_count": number
},
"data": {
"clusters": {
"topics": string[],
"keywords": string[]
}[],
"outliers": {
"topics": string[],
"keywords": string[]
} | null
}
}
Meta endpoints
The following endpoints provide you with information on applicable parameter values for the tools of HyperSuggest. The information returned by these endpoints is very static and will only ever change when a new API version is introduced. As such, these endpoints are intended to be used as a lookup while setting up your API client and you should not query them after finalizing its implementation.
GET /meta/suggest/google
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/google
tool.
Success data
{
"countries": {
"us": {
"name": "United States",
"languages": {
"en": "English",
"es": "Spanish"
}
},
...
}
}
GET /meta/suggest/images
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/images
tool.
Success data
{
"countries": {
"us": {
"name": "United States",
"languages": {
"en": "English",
"es": "Spanish"
}
},
...
}
}
GET /meta/suggest/news
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/news
tool.
Success data
{
"countries": {
"us": {
"name": "United States",
"languages": {
"en": "English",
"es": "Spanish"
}
},
...
}
}
GET /meta/suggest/shopping
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/shopping
tool.
Success data
{
"countries": {
"us": {
"name": "United States",
"languages": {
"en": "English",
"es": "Spanish"
}
},
...
}
}
GET /meta/suggest/youtube
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/youtube
tool.
Success data
{
"countries": {
"us": {
"name": "United States",
"languages": {
"en": "English",
"es": "Spanish"
}
},
...
}
}
GET /meta/suggest/amazon
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/amazon
tool.
Success data
{
"marketplaces": {
"us": {
"name": "United States",
"cateogries": {
"aps": "All Departments",
"arts-crafts-intl-ship": "Arts & Crafts",
"automotive-intl-ship": "Automotive",
"baby-products-intl-ship": "Baby",
"beauty-intl-ship": "Beauty & Personal Care",
...
}
},
...
}
}
GET /meta/suggest/ebay
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/ebay
tool.
Success data
{
"shops": {
"us": "United States",
"es": "Spain",
"de": "Germany",
...
}
}
GET /meta/suggest/instagram
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/instagram
tool.
Success data
{
"countries": {
"us": "United States",
"de": "Germany",
"fr": "France",
"au": "Australia",
...
}
}
GET /meta/suggest/pinterest
This endpoint is intended to be used as a lookup for valid parameter values for the suggest/pinterest
tool.
Success data
{
"countries": {
"us": "United States",
"de": "Germany",
"fr": "France",
"au": "Australia",
...
}
}
GET /meta/wh/google
This endpoint is intended to be used as a lookup for valid parameter values for the wh/google
tool.
Success data
{
"countries": {
"us": {
"name": "United States",
"languages": {
"en": "English",
"es": "Spanish"
}
},
...
}
}
GET /meta/metrics/google
This endpoint is intended to be used as a lookup for valid parameter values for the metrics/google
tool.
Success data
{
"countries": {
"us": {
"name": "United States",
"languages": {
"en": "English",
"es": "Spanish"
}
},
...
}
}