Overview

Jungle Scout's API is structured according to the REST standard, following the JSON API Format 1.0 specification as closely as possible.

This API makes use of different HTTP methods in order to organize its endpoint URL's around the concept of resources.

Error responses make use of different HTTP status codes along with internal error codes and descriptions for easier readability. Error details might change between endpoints but you can see a general list in our errors section.

All requests must have https://developer.junglescout.com as its base address.

Mime Type

This API only responds to the application/vnd.api+json mime type. Please make sure to specify this value within the Content-Type header for all your requests. Expect the same value returned in the same header of your response.

Authentication

As part of the authentication process, please be aware that the API requires you to activate Two-Factor Authentication first. You can enable it by going to your Account Information page.

Once Two-Factor Authentication is enabled, all requests to the API must contain the following:

  • Authorization header
  • marketplace query parameter

Authorization Header

In order to build the Authorization header for your requests, you need to generate an API key, which you can get through your Account Settings page.

After generating your key, you should take note of these 2 values:

  • Application Name
  • API Key (Only visible during generation process)

Given those values, you must send the Authorization header in all your requests with the following value (notice the : character between both values):

APP_NAME:API_KEY

Marketplace Parameter

All requests to the API must contain a marketplace parameter in your query string. The API supports any of the following country codes: us, uk, de, in, ca, fr, it, es, mx, jp. It is important to note that all API Keys attached to your account are also linked to a sub-set of supported country codes. Make sure the marketplace parameter in your requests always points to one of the allowed countries for your API Key.

Versioning

Jungle Scout uses a header approach for versioning. The proper version must be sent within the Accept header and it must follow the format application/vnd.junglescout.vX+json, where X must be replaced by the desired version. Please note that this header must be present in all requests.

As of now, Jungle Scout API only offers version 1, which means, the API always expects the application/vnd.junglescout.v1+json value.

Schema

All API requests and response bodies adhere to a common JSON format representing individual items, collections of items, links to related items and additional metadata.

Request Body and Response

All POST / PUT requests are expected to have a root element object called data, where the client is expected to put the desired payload, usually representing a resource to be created.

  {
    "data": {
      ... rest of the payload, usually representing a resource.
    }
  }

Similarly, all successful responses will always have a root data object containing the response in question. The object contained should describe either a single resource or a collection of resources.

Single Resource

Individual resources are always represented by an object identified with a type and id attributes, along with an attributes object containing the rest of the data.

This structure is expected within the body of a POST / PUT request, and is also the structure returned by endpoints that deal with a single resource. The id attribute in particular is not expected within POST requests since the resource in question is just being created.

  {
    "type": "segment",
     "id": "123",
     "attributes": {
       "name": ...,
       "total_brands": ...,
     }
  }

Resource Collection

Collections of resources are represented as an array inside the previously mentioned data object. Each object inside the collection is expected to have at least the type and id attributes.

  {
      "data": [
          {
              "id": "us/B088WVF1V1",
              "type": "product_database_result",
              "attributes": {
                  "title": "Product Title 1",
                  "price": 22.99,
              }
          },
          {
              "id": "us/B075YT5K59",
              "type": "product_database_result",
              "attributes": {
                  "title": "Product Title 2",
                  "price": 42.49,
              }
          }
      ]
  }

Links

Single and collection results may provide a links object, which contain references to a related resource (single resource result) or to the next page (collection result).

The following snippet depicts an example of a collection response containing a link to itself and another one to fetch the next piece of data. Take a look at the pagination section for more details on the links[next] attribute.

  {
      "data": [ ...omitted for brevity ],
      "meta": { ...omitted for brevity },
      "links": {
          "self": "https://developer.junglescout.com/api/product_database_query?marketplace=us",
          "next": "https://developer.junglescout.com/api/product_database_query?marketplace=us&page%5Bcursor%5D=eyJwYWdpbmF0ZV9mcm9tIjo1MCwicGFnZV9zaXplIjo1MH0%3D%0A"
      }
  }

Meta

Some responses contain data that might not be directly related to the resources themselves. In those cases, a meta attribute object is returned. As of now, the main usage for this object is to report the amount of total_items available in a collection response.

  {
      "data": [ ...omitted for brevity ],
      "links": { ...omitted for brevity },
      "meta": {
        "total_items": 1200
      }
  }

Testing Access

The best way to test your access to the API is by sending a simple request to one of the endpoints. Feel free to copy any of the following client request examples and run it in your environment. Make sure to replace the values for MY_APP and MY_API_KEY with the values you got when generating your API Key.

curl
      curl --location \
          --request POST 'https://developer.junglescout.com/api/product_database_query?marketplace=us' \
          --header 'Accept: application/vnd.junglescout.v1+json' \
          --header 'Content-Type: application/vnd.api+json' \
          --header 'Authorization: MY_APP:MY_API_KEY' \
          --data-raw '{
              "data": {
                  "type": "product_database_query",
                  "attributes": {
                      "include_keywords": ["videogames"],
                      "categories": ["Video Games"],
                      "exclude_unavailable_products": true
                  }
              }
          }'
    

 

ruby / typhoeus
      require 'typhoeus'

      #prepare request headers/body
      request = Typhoeus::Request.new(
        'https://developer.junglescout.com/api/product_database_query',
        method: :post,
        params: { marketplace: 'us' },
        body: {
          data: {
            type: 'product_database_query',
            attributes: {
              categories: ['Video Games'],
              include_keywords: ['videogames'],
              exclude_unavailable_products: true
            }
          }
        }.to_json,
        headers: {
          'Content-Type' => 'application/vnd.api+json',
          'Accept' => 'application/vnd.junglescout.v1+json',
          'Authorization' => 'MY_APP:MY_API_KEY'
        }
      )

      #prepare complete callback
      request.on_complete do |response|
        if response.success?
          puts JSON.parse(response.body)['data']
        else
          puts "HTTP request failed: #{response.code}"
          puts JSON.parse(response.body)
        end
      end

      #execute!
      request.run
    

Please notice the presence of the marketplace query parameter and the Accept, Content-Type and Authorization headers. All of these are required as mentioned in previous sections.

Sorting

Some endpoints dealing with a collection of results might expose the ability to sort the items by a particular field. Usually only one field can be used at a given time. In order to specify a sorting field, the client must send the sort query parameter with the desired field if an ascending order is desired. A value like -field should be used in order to get a descending order.

The following example depicts the usage of the sort parameter to order results by name, desc

      POST https://developer.junglescout.com/api/product_database_query?marketplace=us&sort=-name
           [...headers omitted for brevity]
    

Filtering

Some endpoints dealing with a collection of results might expose the ability to filter the results through one or more fields. In order to specify one or more filters, the client is expected to send the filter query parameter with as many different filters as desired / allowed, using the format, filter[field] = value

The following example depicts the usage of the filter parameter to filter segments that have a certain name pattern

      GET https://developer.junglescout.com/api/segments?marketplace=us&filter[name]=sports
           [...headers omitted for brevity]
    

Throttling

Our API has a rate limit of 150 requests per minute, per account. When the limit is surpassed, the API will return a response with http code 429 along with a body similar to the following:

        {
          "errors": [
              {
                  "title": "Too many requests",
                  "code": "REQUEST_THROTTLED",
                  "detail": "retry again at 2021-03-19T00:55:19-06:00"
              }
          ]
        }
      

Errors

HTTP Status Codes

This API uses HTTP status codes and internal error codes to indicate that something went wrong when trying to process a request. The following is a list of general errors but please be aware that each endpoint will provide specifics when an error is being reported.

HTTP Code Description
400 The request could not be processed, usually due to a missing or invalid parameter
403 The request is not authenticated or has no authorization over the given marketplace country code
404 Either the endpoint or the requested resource does not exist
415 The Content-Type header has an unexpected value
422 A resource could not be created / updated due to invalid parameter values
429 The request has been throttled
500 An unexpected error occurred, Jungle Scout developers are notified when this happens

API Error Codes

When an error is raised, the error object returned in the response body will always have a code attribute. The following table shows the possible error codes, their descriptions, and suggested fixes.

API Error Code Description Suggested Fix
VALIDATION_ERROR The request body cannot be successfully validated and then processed Update request body to ensure it conforms to the schema requirements. Check the endpoint documentation for required query parameters.
INVALID_SORT_CRITERIA The sort field provided is invalid Check the detail attribute of the error. Use one of the supported sort fields or check the endpoint documentation for a list of supported sort fields for the endpoint.
INVALID_PAGE_OBJECT page parameters are invalid Use pagination parameters as described in the endpoint documentation.
INVALID_VERSION The 'Accept' header is invalid Refer to ther versioning for all accepted `Accept` header values and use one of the accepted `Accept` headers as described.
INVALID_MARKETPLACE Invalid marketplace query parameter Update the marketplaces parameter to include only accepted marketplaces as listed in the endpoint documentation.
INVALID_PAGE_SIZE Invalid page size parameter Update page size parameter to a valid value per the endpoint documentation.
INVALID_COMPARISON_PERIOD translation missing: en.api_errors.invalid_comparison_period.description translation missing: en.api_errors.invalid_comparison_period.suggested_fix
BAD_REQUEST The request contains invalid query parameters, headers, and/or bodies Check/Update request headers to conform to the API documentation. Check/Update request body to conform to applicable endpoint schema.
FORBIDDEN User is forbidden to perform the request Check if your membership has access to the resource/endpoint requested. Contact support if you do not have the required access.
RECORD_NOT_FOUND We could not locate the resource with the id provided Update the the id parameter with an id for an existing resource.
NOT_ACCEPTABLE Invalid 'Accept' header Use one of the accepted `Accept` headers as described in the endpoint documentation.
UNSUPPORTED_MEDIA_TYPE Invalid 'Content-Type' header Use one of the accepted 'Content-Type' headers for the endpoint.
UNPROCESSABLE_ENTITY The request contains invalid parameters or bodies Ensure all query parameters contain valid values and the request body conforms to the schema requirements in the endpoint documentation.
INTERNAL_SERVER_ERROR Something went wrong with our internal server Contact Jungle Scout Customer Support with details about the error.
INVALID_ASIN Invalid Amazon Serial Identification Number Update your ASIN with valid value.
MISSING_RANK_DATA We do not have enough rank data for the given date range to calculate estimated sales for ASIN provided Try the request at a later time.
UNSUPPORTED_CATEGORY_VALUE Category value for ASIN provided is not currently supported Try the request at a later time.
CANNOT_FETCH_PRODUCT We cannot fetch the product data for the ASIN provided Internal error. Try the request at a later time.

Errors Schema

Any error returned by the API is expected to have a root errors attribute containing an array of items, where each item is expected to have at least four attributes: title, detail, code, status. The following snippet depicts an error example returned by this API.

      {
        "errors": [
          {
            "title": "Unsupported media type",
            "detail": "All requests must use the 'application/vnd.api+json' Content-Type. This request specified 'text/plain'.",
            "code": "UNSUPPORTED_MEDIA_TYPE",
            "status": "415"
          }
        ]
      }
    

Take a look at the following table for a more detailed explanation for each one of these fields.

Attribute Description Notes
title Contains a short, human-readable summary of the problem that does not change from occurrence to occurrence of the problem. This value may be subject to localization in the future.
detail A human-readable explanation specific to this occurrence of the problem. This value may be subject to localization in the future.
code An application-specific error code, expressed as a string value. This value is not subject to localization. If your client code needs to perform a custom action depending on specific errors, we recommend using this value.
status The HTTP status code applicable to this problem, expressed as a string value. In some cases, a single HTTP status error code might be used by several code values. For instance, 400 Bad Request might be used by internal codes like INVALID_SORT_CRITERIA and INVALID_MARKETPLACE
source The offending query parameter or request body attribute

When the error is caused by a query parameter, expect source to point to an object with the parameter attribute. e.g.
{ source: { parameter: 'sort' } }.

When the error is caused by an attribute in the request body, expect source to point to an object with the pointer attribute. e.g.
{ source: { pointer: 'data/attributes/price' } }.

Endpoints