Login Start now
Intro
What is seospark.io? The workflow Getting Started
Learning
Keyword Discovery Ranked keywords People Also Asked Metrics Tool Clustering Rank Tracking
Pricing
Subscription Credits on Demand
Use Cases
Use case: Content gaps

API

General

The seospark API allows you to access the tools of seospark through a programmable HTTP interface. Access to the API is not included by default in the subscription bundles available for seospark. You will need to submit an individual request here in order to access the API.

Core concept

seospark 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 seospark 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 seospark 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 seospark 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. The Content-Type HTTP header is set accordingly.

  • Response payloads are in JSON format with keys following the snake_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, since error_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:

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-seospark-ApiKey request header field. If you are subscribed to a version of seospark that includes API access, you can find your API key in the account page of the seospark 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
    The X-seospark-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
    The Accept-Encoding HTTP header is missing the gzip option. More info.

  • rate_limit_exceeded :429
    You have made too many requests to this endpoint and the rate limit is in effect. The Retry-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

  1. If you are subscribed to a version of seospark that includes API access, find your API key in the account page of the seospark dashboard.
  2. Try the request below to fetch information about your account’s access status.
curl -X GET \
     -H "X-seospark-ApiKey: YOUR_API_KEY" \
     --compressed \
     https://api.hypersuggest.com/account/access

  1. You should see a response describing your account’s current access and quota status similar to the example here.

  2. (Optional) We have prepared a Postman collection ready for you to explore and use as a starting point for your integration of the seospark API. The collection includes all endpoints and example payloads. Remember to set the api_key variable in Postman to your own API key.

    Run in Postman

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. The message 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 seospark. 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"
            }
        },
        ...
    }
}
Table of contents