openapi: 3.0.3 info: title: EverBee Research Open API version: 1.0.0 description: | # EverBee Research API Interactive reference for **`GET /api/v1/*`** on **https://research-open-api.everbee.com**. **Authentication:** Send **`client_id`** and **`client_secret`** from the EverBee Dev Portal on every request (see **Authorize** → ClientIDAuth + ClientSecretAuth). The API resolves the installing user and applies subscription-appropriate listing fields. **Apps work on every plan.** Calls with `client_id`/`client_secret` are paid from the app owner's API credits and return the full data set on any EverBee plan, Hobby included. Signed-in MCP calls (Claude, ChatGPT) need a paid plan: Hobby accounts receive `403` with `{"error": "…", "code": "paid_plan_required"}`, and data follows the caller's plan. **Developer guide (auth, CORS, rate limits):** open **`/docs/research-open-api-guide.html`** on the same host as the API — for example **https://research-open-api.everbee.com/docs/research-open-api-guide.html**. **Try it out:** Authorize, set query/path params, run requests from this UI. servers: - url: 'https://research-open-api.everbee.com' description: Production server components: securitySchemes: ClientIDAuth: type: apiKey in: header name: client_id description: | Application identifier from the EverBee Dev Portal. Send on every request with `client_secret`. ClientSecretAuth: type: apiKey in: header name: client_secret description: | Application secret from the EverBee Dev Portal. Used with `client_id` to resolve the installing user and apply plan-based data visibility. headers: Access-Control-Allow-Origin: description: CORS — allowed origin (research-open-api.everbee.com). schema: type: string example: '*' Access-Control-Allow-Headers: description: CORS — request headers allowed for cross-origin calls. schema: type: string example: client_id, client_secret, Content-Type Access-Control-Allow-Methods: description: CORS — HTTP methods allowed for cross-origin calls. schema: type: string example: GET, OPTIONS schemas: {} security: - ClientIDAuth: [] ClientSecretAuth: [] tags: - name: Shops description: APIs to get shops data, details, and listings. - name: Listings description: APIs to get listing data, update listings, and metrics. - name: Keywords description: APIs for keyword research, trends, and analytics. - name: Product Ideas description: >- Spike endpoint for validating a product idea before selling it — directional only, not yet the full opportunity-scored version. paths: /api/v1/listings: get: tags: - Listings summary: Get Product Analytics for Listings description: Retrieve analytical data for product listings based on various filters. parameters: # Pagination & Sorting - in: query name: order_by schema: type: string description: Field to sort by (any of the listed filter fields) - in: query name: order_direction schema: type: string enum: - asc - desc description: Sort direction (ascending or descending) - in: query name: page schema: type: integer description: Page number for pagination required: true - in: query name: per_page schema: type: integer description: Number of results per page required: true - in: query name: currency schema: type: string description: Currency code (e.g. USD) - in: query name: time_range schema: type: string description: 'Time range (e.g. last_30_days, last_1_month, etc.)' # Range Filters - name: tags_used_min in: query schema: type: number description: Minimum number of tags used - name: tags_used_max in: query schema: type: number description: Maximum number of tags used - name: visibility_score_min in: query schema: type: number description: Minimum visibility score - name: visibility_score_max in: query schema: type: number description: Maximum visibility score - name: listing_age_in_months_min in: query schema: type: number description: Minimum listing age in months - name: listing_age_in_months_max in: query schema: type: number description: Maximum listing age in months - name: conversion_rate_min in: query schema: type: number description: Minimum conversion rate - name: conversion_rate_max in: query schema: type: number description: Maximum conversion rate - name: price_min in: query schema: type: number description: Minimum price - name: price_max in: query schema: type: number description: Maximum price - name: num_favorers_min in: query schema: type: number description: Minimum number of favorers - name: num_favorers_max in: query schema: type: number description: Maximum number of favorers - name: views_min in: query schema: type: number description: Minimum number of views - name: views_max in: query schema: type: number description: Maximum number of views - name: processing_min_min in: query schema: type: number description: Minimum processing time in minutes - name: processing_min_max in: query schema: type: number description: Maximum processing time in minutes - name: shop_age_month_min in: query schema: type: number description: Minimum shop age in months - name: shop_age_month_max in: query schema: type: number description: Maximum shop age in months - name: digital_listing_count_min in: query schema: type: number description: Minimum digital listing count - name: digital_listing_count_max in: query schema: type: number description: Maximum digital listing count - name: title_character_count_min in: query schema: type: number description: Minimum title character count - name: title_character_count_max in: query schema: type: number description: Maximum title character count - name: est_reviews_min in: query schema: type: number description: Minimum estimated reviews - name: est_reviews_max in: query schema: type: number description: Maximum estimated reviews - name: est_reviews_in_months_min in: query schema: type: number description: Minimum estimated reviews in given months - name: est_reviews_in_months_max in: query schema: type: number description: Maximum estimated reviews in given months - name: est_total_sales_min in: query schema: type: number description: Minimum estimated total sales - name: est_total_sales_max in: query schema: type: number description: Maximum estimated total sales - name: transaction_sold_count_min in: query schema: type: number description: Minimum transaction sold count - name: transaction_sold_count_max in: query schema: type: number description: Maximum transaction sold count - name: est_mo_revenue_min in: query schema: type: number description: Minimum estimated revenue in selected time_range - name: est_mo_revenue_max in: query schema: type: number description: Maximum estimated revenue in selected time_range - name: est_mo_sales_min in: query schema: type: number description: Minimum estimated sales in selected time_range - name: est_mo_sales_max in: query schema: type: number description: Maximum estimated sales in selected time_range # Time Range Filters - name: growth_rate_min in: query schema: type: number description: Minimum growth rate in selected time_range - name: growth_rate_max in: query schema: type: number description: Maximum growth rate in selected time_range - name: shop_name_include in: query schema: type: string description: Include listings by matching shop name - name: category_include in: query schema: type: string description: Include listings by matching category - name: shipping_from_country_iso in: query schema: type: string description: Filter by shipping from country ISO code - name: title_include in: query schema: type: string description: Include listings with matching title text # String Filters - name: listing_type in: query schema: type: string description: Filter by listing type (physical/digital) - name: shop_name_exclude in: query schema: type: string description: Exclude listings by shop name - name: category_exclude in: query schema: type: string description: Exclude listings by category - name: title_exclude in: query schema: type: string description: Exclude listings with matching title text - name: is_customizable in: query schema: type: boolean description: Whether the listing is customizable # Exclusion Filters - name: is_personalizable in: query schema: type: boolean description: Whether the listing is personalizable - name: has_variations in: query schema: type: boolean description: Whether the listing has variations - name: is_supply in: query schema: type: boolean description: Whether the listing is marked as a supply # Boolean Filters responses: '200': description: Successful response with listings analytics data headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' content: application/json: schema: type: object properties: current_page: type: integer example: 1 total_count: type: integer example: 172815236 total_pages: type: integer example: 172815236 results: type: array items: type: object properties: listing_id: type: integer nullable: true currency_code: type: string nullable: true title: type: string nullable: true state: type: string nullable: true original_creation_tsz: type: integer nullable: true created_at: type: string format: date-time nullable: true reindexed_at: type: string format: date-time nullable: true quantity: type: integer nullable: true price: type: string nullable: true tags: type: array nullable: true items: type: string url: type: string nullable: true num_favorers: type: integer nullable: true shop_age_month: type: integer nullable: true shop_name: type: string nullable: true transaction_sold_count: type: integer nullable: true digital_listing_count: type: integer nullable: true is_customizable: type: boolean nullable: true is_personalizable: type: boolean nullable: true has_variations: type: boolean nullable: true is_supply: type: boolean nullable: true processing_min: type: integer nullable: true shipping_from_country_iso: type: string nullable: true when_made: type: string nullable: true who_made: type: string nullable: true views: type: integer nullable: true main_category: type: string nullable: true listing_type: type: string nullable: true should_auto_renew: type: boolean nullable: true featured_rank: type: integer nullable: true shop_id: type: string nullable: true shop_review_ratio: type: number format: float nullable: true Images: type: string nullable: true Shop: type: object nullable: true properties: shop_name: type: string nullable: true shop_id: type: integer nullable: true shop_age_month: type: integer nullable: true transaction_sold_count: type: integer nullable: true digital_listing_count: type: integer nullable: true review_rate: type: number format: float nullable: true trends: type: array nullable: true items: type: string id: type: string nullable: true listing_age_in_months: type: integer nullable: true est_mo_sales: type: integer nullable: true description: >- Estimated sales for the selected `time_range`, as that window's TOTAL -- NOT a monthly average. Only at the default `last_1_month` is this a monthly figure; use `cached_est_mo_sales` for a monthly rate on any other window. est_mo_revenue: type: number format: float nullable: true cached_est_mo_sales: type: integer nullable: true description: >- Estimated sales for the LAST MONTH, independent of `time_range`. Use this for a monthly rate; `est_mo_sales` is the selected window's TOTAL (a 24-month range returns a 24-month total, not a monthly average). cached_est_mo_revenue: type: number format: float nullable: true description: >- Estimated revenue for the LAST MONTH, independent of `time_range`. The revenue counterpart of `cached_est_mo_sales`. est_reviews: type: integer nullable: true est_reviews_in_months: type: integer nullable: true est_total_sales: type: integer nullable: true description: >- Estimated lifetime sales. Same estimator the `est_total_sales_min`/`_max` filters and `order_by=est_total_sales` resolve to, so filtering, sorting and this value always agree. growth_rate: type: number format: float nullable: true is_fav: type: boolean nullable: true tags_used: type: integer nullable: true curreny_symbol: type: string nullable: true tags_count: type: integer nullable: true title_character_count: type: integer nullable: true visibility_score: type: number format: float nullable: true conversion_rate: type: number format: float nullable: true last_modified_listing_date: type: string format: date-time nullable: true taxonomy_path: type: array nullable: true items: type: string examples: Example 1: value: current_page: 1 total_count: 172815236 total_pages: 172815236 results: - listing_id: 0 currency_code: string title: string state: string original_creation_tsz: 0 created_at: '2019-08-24T14:15:22Z' quantity: 0 price: string tags: - string url: string num_favorers: 0 shop_age_month: 0 shop_name: string transaction_sold_count: 0 digital_listing_count: 0 is_customizable: true is_personalizable: true has_variations: true is_supply: true processing_min: 0 shipping_from_country_iso: string when_made: string who_made: string views: 0 main_category: string listing_type: string should_auto_renew: true featured_rank: 0 shop_id: string shop_review_ratio: -3.402823669209385e+38 Images: string Shop: shop_name: string shop_id: 0 shop_age_month: 0 transaction_sold_count: 0 digital_listing_count: 0 review_rate: -3.402823669209385e+38 trends: - string id: string listing_age_in_months: 0 est_mo_sales: 0 est_mo_revenue: -3.402823669209385e+38 cached_est_mo_sales: 0 cached_est_mo_revenue: -3.402823669209385e+38 est_reviews: 0 est_reviews_in_months: 0 est_total_sales: 0 growth_rate: -3.402823669209385e+38 is_fav: true tags_used: 0 curreny_symbol: string tags_count: 0 title_character_count: 0 visibility_score: -3.402823669209385e+38 conversion_rate: -3.402823669209385e+38 last_modified_listing_date: '2019-08-24T14:15:22Z' taxonomy_path: - string '400': description: Bad Request headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' '401': description: Unauthorized headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' '/api/v1/shops/{shop_name}/listings': get: tags: - Shops summary: Get all listings for a specific shop description: Returns a paginated list of listings for a given shop parameters: - in: path name: shop_name required: true schema: type: string description: The shop name to fetch listings for - in: query name: order_by schema: type: string description: Field to sort by (any of the listed filter fields) - in: query name: order_direction schema: type: string enum: - asc - desc description: Sort direction (ascending or descending) - in: query name: page schema: type: integer description: Page number for pagination required: true - in: query name: per_page schema: type: integer description: Number of results per page required: true - in: query name: currency schema: type: string description: Currency code (e.g. USD) - in: query name: time_range schema: type: string description: 'Time range (e.g. last_30_days, last_1_month, etc.)' - name: tags_used_min in: query schema: type: number description: Minimum number of tags used - name: tags_used_max in: query schema: type: number description: Maximum number of tags used - name: visibility_score_min in: query schema: type: number description: Minimum visibility score - name: visibility_score_max in: query schema: type: number description: Maximum visibility score - name: listing_age_in_months_min in: query schema: type: number description: Minimum listing age in months - name: listing_age_in_months_max in: query schema: type: number description: Maximum listing age in months - name: conversion_rate_min in: query schema: type: number description: Minimum conversion rate - name: conversion_rate_max in: query schema: type: number description: Maximum conversion rate - name: price_min in: query schema: type: number description: Minimum price - name: price_max in: query schema: type: number description: Maximum price - name: num_favorers_min in: query schema: type: number description: Minimum number of favorers - name: num_favorers_max in: query schema: type: number description: Maximum number of favorers - name: views_min in: query schema: type: number description: Minimum number of views - name: views_max in: query schema: type: number description: Maximum number of views - name: processing_min_min in: query schema: type: number description: Minimum processing time in minutes - name: processing_min_max in: query schema: type: number description: Maximum processing time in minutes - name: shop_age_month_min in: query schema: type: number description: Minimum shop age in months - name: shop_age_month_max in: query schema: type: number description: Maximum shop age in months - name: digital_listing_count_min in: query schema: type: number description: Minimum digital listing count - name: digital_listing_count_max in: query schema: type: number description: Maximum digital listing count - name: title_character_count_min in: query schema: type: number description: Minimum title character count - name: title_character_count_max in: query schema: type: number description: Maximum title character count - name: est_reviews_min in: query schema: type: number description: Minimum estimated reviews - name: est_reviews_max in: query schema: type: number description: Maximum estimated reviews - name: est_reviews_in_months_min in: query schema: type: number description: Minimum estimated reviews in given months - name: est_reviews_in_months_max in: query schema: type: number description: Maximum estimated reviews in given months - name: est_total_sales_min in: query schema: type: number description: Minimum estimated total sales - name: est_total_sales_max in: query schema: type: number description: Maximum estimated total sales - name: transaction_sold_count_min in: query schema: type: number description: Minimum transaction sold count - name: transaction_sold_count_max in: query schema: type: number description: Maximum transaction sold count - name: est_mo_revenue_min in: query schema: type: number description: Minimum estimated revenue in selected time_range - name: est_mo_revenue_max in: query schema: type: number description: Maximum estimated revenue in selected time_range - name: est_mo_sales_min in: query schema: type: number description: Minimum estimated sales in selected time_range - name: est_mo_sales_max in: query schema: type: number description: Maximum estimated sales in selected time_range - name: growth_rate_min in: query schema: type: number description: Minimum growth rate in selected time_range - name: growth_rate_max in: query schema: type: number description: Maximum growth rate in selected time_range - name: shop_name_include in: query schema: type: string description: Include listings by matching shop name - name: category_include in: query schema: type: string description: Include listings by matching category - name: shipping_from_country_iso in: query schema: type: string description: Filter by shipping from country ISO code - name: title_include in: query schema: type: string description: Include listings with matching title text - name: listing_type in: query schema: type: string description: Filter by listing type (physical/digital) - name: shop_name_exclude in: query schema: type: string description: Exclude listings by shop name - name: category_exclude in: query schema: type: string description: Exclude listings by category - name: title_exclude in: query schema: type: string description: Exclude listings with matching title text - name: is_customizable in: query schema: type: boolean description: Whether the listing is customizable - name: is_personalizable in: query schema: type: boolean description: Whether the listing is personalizable - name: has_variations in: query schema: type: boolean description: Whether the listing has variations - name: is_supply in: query schema: type: boolean description: Whether the listing is marked as a supply responses: '200': description: Successful response with listings analytics data headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' content: application/json: schema: type: object properties: current_page: type: integer example: 1 total_count: type: integer example: 172815236 total_pages: type: integer example: 172815236 results: type: array items: type: object properties: listing_id: type: integer nullable: true currency_code: type: string nullable: true title: type: string nullable: true state: type: string nullable: true original_creation_tsz: type: integer nullable: true created_at: type: string format: date-time nullable: true quantity: type: integer nullable: true price: type: string nullable: true tags: type: array nullable: true items: type: string url: type: string nullable: true num_favorers: type: integer nullable: true shop_age_month: type: integer nullable: true shop_name: type: string nullable: true transaction_sold_count: type: integer nullable: true digital_listing_count: type: integer nullable: true is_customizable: type: boolean nullable: true is_personalizable: type: boolean nullable: true has_variations: type: boolean nullable: true is_supply: type: boolean nullable: true processing_min: type: integer nullable: true shipping_from_country_iso: type: string nullable: true when_made: type: string nullable: true who_made: type: string nullable: true views: type: integer nullable: true main_category: type: string nullable: true listing_type: type: string nullable: true should_auto_renew: type: boolean nullable: true featured_rank: type: integer nullable: true shop_id: type: string nullable: true shop_review_ratio: type: number format: float nullable: true Images: type: string nullable: true Shop: type: object nullable: true properties: shop_name: type: string nullable: true shop_id: type: integer nullable: true shop_age_month: type: integer nullable: true transaction_sold_count: type: integer nullable: true digital_listing_count: type: integer nullable: true review_rate: type: number format: float nullable: true trends: type: array nullable: true items: type: string id: type: string nullable: true listing_age_in_months: type: integer nullable: true est_mo_sales: type: integer nullable: true description: >- Estimated sales for the selected `time_range`, as that window's TOTAL -- NOT a monthly average. Only at the default `last_1_month` is this a monthly figure; use `cached_est_mo_sales` for a monthly rate on any other window. est_mo_revenue: type: number format: float nullable: true cached_est_mo_sales: type: integer nullable: true description: >- Estimated sales for the LAST MONTH, independent of `time_range`. Use this for a monthly rate; `est_mo_sales` is the selected window's TOTAL (a 24-month range returns a 24-month total, not a monthly average). cached_est_mo_revenue: type: number format: float nullable: true description: >- Estimated revenue for the LAST MONTH, independent of `time_range`. The revenue counterpart of `cached_est_mo_sales`. est_reviews: type: integer nullable: true est_reviews_in_months: type: integer nullable: true est_total_sales: type: integer nullable: true description: >- Estimated lifetime sales. Same estimator the `est_total_sales_min`/`_max` filters and `order_by=est_total_sales` resolve to, so filtering, sorting and this value always agree. growth_rate: type: number format: float nullable: true is_fav: type: boolean nullable: true tags_used: type: integer nullable: true curreny_symbol: type: string nullable: true tags_count: type: integer nullable: true title_character_count: type: integer nullable: true visibility_score: type: number format: float nullable: true conversion_rate: type: number format: float nullable: true last_modified_listing_date: type: string format: date-time nullable: true taxonomy_path: type: array nullable: true items: type: string examples: Example 1: value: current_page: 1 total_count: 172815236 total_pages: 172815236 results: - listing_id: 0 currency_code: string title: string state: string original_creation_tsz: 0 created_at: '2019-08-24T14:15:22Z' quantity: 0 price: string tags: - string url: string num_favorers: 0 shop_age_month: 0 shop_name: string transaction_sold_count: 0 digital_listing_count: 0 is_customizable: true is_personalizable: true has_variations: true is_supply: true processing_min: 0 shipping_from_country_iso: string when_made: string who_made: string views: 0 main_category: string listing_type: string should_auto_renew: true featured_rank: 0 shop_id: string shop_review_ratio: -3.402823669209385e+38 Images: string Shop: shop_name: string shop_id: 0 shop_age_month: 0 transaction_sold_count: 0 digital_listing_count: 0 review_rate: -3.402823669209385e+38 trends: - string id: string listing_age_in_months: 0 est_mo_sales: 0 est_mo_revenue: -3.402823669209385e+38 cached_est_mo_sales: 0 cached_est_mo_revenue: -3.402823669209385e+38 est_reviews: 0 est_reviews_in_months: 0 est_total_sales: 0 growth_rate: -3.402823669209385e+38 is_fav: true tags_used: 0 curreny_symbol: string tags_count: 0 title_character_count: 0 visibility_score: -3.402823669209385e+38 conversion_rate: -3.402823669209385e+38 last_modified_listing_date: '2019-08-24T14:15:22Z' taxonomy_path: - string '400': description: Bad Request headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' '401': description: Unauthorized headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' parameters: [] '/api/v1/listings/{listing_id}': get: summary: Get Listing Details tags: - Listings responses: '200': description: OK headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' content: application/json: schema: type: object x-examples: Example 1: listing: listing_id: 123456789 currency_code: USD title: Taylor and Kent Teacup Tea Cup and Saucer Made in Longton England 9228 state: sold_out original_creation_tsz: 1360702792 created_at: '2013-02-12T20:59:52.000Z' reindexed_at: '2025-05-06T10:55:12.600+00:00' quantity: 0 price: '17.31' tags: - teacup - british tea - cups and saucers - bone china - staffordshire - crown cup saucer - taylor and kent - cup and saucer - vintage teacups - vintage cups - longton - english tea url: 'https://www.etsy.com/listing/123456789/taylor-and-kent-teacup-tea-cup-and' num_favorers: 14 shop_age_month: 174 shop_name: TheVintageTeacup transaction_sold_count: 5052 digital_listing_count: 0 is_customizable: false is_personalizable: false has_variations: false is_supply: false processing_min: 1 shipping_from_country_iso: null when_made: 1950s who_made: someone_else views: 0 main_category: Home & Living listing_type: physical should_auto_renew: false featured_rank: -1 shop_id: f239c412-803e-49c1-a7ed-5972bff6c1df shop_review_ratio: null Images: 'https://i.etsystatic.com/6069646/r/il/616d87/426946486/il_170x135.426946486_ax2z.jpg' Shop: shop_name: TheVintageTeacup shop_id: 6069646 shop_age_month: 174 transaction_sold_count: 5052 digital_listing_count: 0 review_rate: null trends: [] id: null listing_age_in_months: 146 est_mo_sales: 0 est_mo_revenue: 0 cached_est_mo_sales: 0 cached_est_mo_revenue: 0 est_reviews: 0 est_reviews_in_months: 0 est_total_sales: 0 growth_rate: 0 is_fav: false tags_used: 12 curreny_symbol: $ tags_count: 12 title_character_count: 70 visibility_score: 0 conversion_rate: 0 last_modified_listing_date: null taxonomy_path: [] properties: listing: type: object properties: listing_id: type: integer currency_code: type: string title: type: string state: type: string original_creation_tsz: type: integer created_at: type: string quantity: type: integer price: type: string tags: type: array items: type: string url: type: string num_favorers: type: integer shop_age_month: type: integer shop_name: type: string transaction_sold_count: type: integer digital_listing_count: type: integer is_customizable: type: boolean is_personalizable: type: boolean has_variations: type: boolean is_supply: type: boolean processing_min: type: integer shipping_from_country_iso: type: string when_made: type: string who_made: type: string views: type: integer main_category: type: string listing_type: type: string should_auto_renew: type: boolean featured_rank: type: integer shop_id: type: string shop_review_ratio: type: integer Images: type: string Shop: type: object properties: shop_name: type: string shop_id: type: integer shop_age_month: type: integer transaction_sold_count: type: integer digital_listing_count: type: integer review_rate: type: number trends: type: array items: type: object id: type: string listing_age_in_months: type: integer est_mo_sales: type: integer description: Estimated sales for the selected `time_range`, as that window's TOTAL. est_mo_revenue: type: integer cached_est_mo_sales: type: integer description: Estimated sales for the LAST MONTH, independent of `time_range`. cached_est_mo_revenue: type: integer description: Estimated revenue for the LAST MONTH, independent of `time_range`. est_reviews: type: integer est_reviews_in_months: type: integer est_total_sales: type: integer growth_rate: type: integer is_fav: type: boolean tags_used: type: integer curreny_symbol: type: string tags_count: type: integer title_character_count: type: integer visibility_score: type: integer conversion_rate: type: integer last_modified_listing_date: type: string taxonomy_path: type: array items: type: object examples: Example: value: listing: listing_id: 0 currency_code: string title: string state: string original_creation_tsz: 0 created_at: string quantity: 0 price: string tags: - string url: string num_favorers: 0 shop_age_month: 0 shop_name: string transaction_sold_count: 0 digital_listing_count: 0 is_customizable: true is_personalizable: true has_variations: true is_supply: true processing_min: 0 shipping_from_country_iso: null when_made: string who_made: string views: 0 main_category: string listing_type: string should_auto_renew: true featured_rank: 0 shop_id: string shop_review_ratio: null Images: string Shop: shop_name: string shop_id: 0 shop_age_month: 0 transaction_sold_count: 0 digital_listing_count: 0 review_rate: null trends: - {} id: null listing_age_in_months: 0 est_mo_sales: 0 est_mo_revenue: 0 cached_est_mo_sales: 0 cached_est_mo_revenue: 0 est_reviews: 0 est_reviews_in_months: 0 est_total_sales: 0 growth_rate: 0 is_fav: true tags_used: 0 curreny_symbol: string tags_count: 0 title_character_count: 0 visibility_score: 0 conversion_rate: 0 last_modified_listing_date: null taxonomy_path: - {} operationId: '' description: Get Specific Listing details parameters: - in: path name: listing_id required: true schema: type: string description: Unique listing identifier - schema: type: string in: query name: currency description: ISO currency code for price and revenue fields parameters: [] /api/v1/shops: get: tags: - Shops summary: Get shops analytics description: Returns a paginated list of shops with analytics data parameters: - in: query name: page schema: type: integer default: 1 description: Page number - in: query name: per_page schema: type: integer default: 20 description: Number of results per page - in: query name: shop_name schema: type: string description: Filter by shop name (partial match) - in: query name: shop_location_country_iso schema: type: string description: 'Filter by country ISO code (e.g. US, IN)' - in: query name: min_sales_30_days schema: type: integer description: Filter by minimum sales in last 30 days - in: query name: max_sales_30_days schema: type: integer description: Filter by maximum sales in last 30 days - in: query name: min_revenue_30_days schema: type: number format: float description: Filter by minimum revenue in last 30 days - in: query name: max_revenue_30_days schema: type: number format: float description: Filter by maximum revenue in last 30 days - in: query name: min_conversion_rate schema: type: number format: float description: Filter by minimum conversion rate - in: query name: max_conversion_rate schema: type: number format: float description: Filter by maximum conversion rate - in: query name: order_by schema: type: string enum: - sales_30_days - revenue_30_days - conversion_rate - review_count - average_listing_price description: Field to order by - in: query name: order_direction schema: type: string enum: - asc - desc default: desc description: Order direction responses: '200': description: Successful response with shops analytics data headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' content: application/json: schema: type: object properties: current_page: type: integer example: 1 total_count: type: integer example: 999999 total_pages: type: integer example: 10000 results: type: array items: type: object properties: id: type: string nullable: true shop_id: type: integer nullable: true shop_logo: type: string nullable: true shop_name: type: string nullable: true sales_30_days: type: integer nullable: true transaction_sold_count: type: integer nullable: true revenue_30_days: type: number format: float nullable: true revenue: type: number format: float nullable: true create_date: type: string format: date-time nullable: true review_rate: type: number format: float nullable: true listing_active_count: type: integer nullable: true listings_count: type: integer nullable: true currency_code: type: string nullable: true conversion_rate: type: number format: float nullable: true digital_listing_count: type: integer nullable: true num_favorers: type: integer nullable: true review_count: type: integer nullable: true shop_location_country_iso: type: string nullable: true views: type: integer nullable: true shop_age_month: type: integer nullable: true average_listing_price: type: number format: float nullable: true on_etsy_since: type: string nullable: true sale_per_listing: type: number format: float nullable: true is_shops_getting_analyzed: type: boolean nullable: true is_shops_listing_analyzed: type: boolean nullable: true review_average: type: number format: float nullable: true average_calculated_revenue: type: number format: float nullable: true '/api/v1/shops/{shop_name}': get: tags: - Shops summary: Get shop details description: Returns full analytics data for a specific shop by its name parameters: - in: path name: shop_name required: true schema: type: string description: The shop name to fetch details for responses: '200': description: Successful response with shop details headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' content: application/json: schema: type: object properties: id: type: string nullable: true shop_id: type: integer nullable: true shop_logo: type: string nullable: true shop_name: type: string nullable: true sales_30_days: type: integer nullable: true transaction_sold_count: type: integer nullable: true revenue_30_days: type: number format: float nullable: true revenue: type: number format: float nullable: true create_date: type: string format: date-time nullable: true review_rate: type: number format: float nullable: true listing_active_count: type: integer nullable: true listings_count: type: integer nullable: true currency_code: type: string nullable: true conversion_rate: type: number format: float nullable: true digital_listing_count: type: integer nullable: true num_favorers: type: integer nullable: true review_count: type: integer nullable: true shop_location_country_iso: type: string nullable: true views: type: integer nullable: true shop_age_month: type: integer nullable: true average_listing_price: type: number format: float nullable: true on_etsy_since: type: string nullable: true sale_per_listing: type: number format: float nullable: true is_shops_getting_analyzed: type: boolean nullable: true is_shops_listing_analyzed: type: boolean nullable: true review_average: type: number format: float nullable: true average_calculated_revenue: type: number format: float nullable: true parameters: - schema: type: string name: shop_name in: path required: true description: Shop name /api/v1/keywords: get: tags: - Keywords summary: Get default or trending keyword suggestions with analytics description: 'Returns paginated keyword suggestions with metrics like volume, competition, score, and CPC.' parameters: - in: query name: new_volume_min schema: type: number description: Minimum new search volume - in: query name: new_volume_max schema: type: number description: Maximum new search volume - in: query name: competition_min schema: type: number description: Minimum competition score - in: query name: competition_max schema: type: number description: Maximum competition score - in: query name: score_min schema: type: number description: Minimum keyword score - in: query name: score_max schema: type: number description: Maximum keyword score - in: query name: keyword_include schema: type: string description: Include keywords containing this string - in: query name: keyword_exclude schema: type: string description: Exclude keywords containing this string - in: query name: order_by schema: type: string enum: - vol - competition - score - new_volume description: Field to sort by - in: query name: order_direction schema: type: string enum: - asc - desc default: desc description: Sort order - in: query name: page schema: type: integer default: 1 description: Page number - in: query name: per_page schema: type: integer default: 20 description: Number of results per page responses: '200': description: Successful response with keyword suggestions headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' content: application/json: schema: type: object properties: current_page: type: integer example: 1 total_count: type: integer example: 67360 total_pages: type: integer example: 3368 results: type: array items: type: object properties: _index: type: string nullable: true example: keyword_analytics_development_20240909091534431 _id: type: string nullable: true example: f6a675cd-7e95-4543-8c31-64172ac1513d _score: type: number nullable: true example: null sort: type: array items: type: number example: 24432 keyword: type: string example: cu stom vol: type: integer example: 23180 cpc: type: string example: '0.00' competition: type: number example: 102 created_at: type: string format: date-time example: '2023-04-25T13:15:23.954Z' new_volume: type: number example: 23180 score: type: number example: 24432 id: type: string example: f6a675cd-7e95-4543-8c31-64172ac1513d example: current_page: 1 total_count: 3 total_pages: 1 results: - keyword: cu stom vol: 23180 cpc: '0.00' competition: 102 new_volume: 23180 score: 24432 _id: f6a675cd-7e95-4543-8c31-64172ac1513d _index: keyword_analytics_development_20240909091534431 - keyword: per sonalized vol: 23657 cpc: '0.00' competition: 679 new_volume: 23657 score: 11777.5 _id: 7ade0c78-9773-4611-aae9-58eeaa653256 _index: keyword_analytics_development_20240909091534431 - keyword: printable printabll vol: 5316 cpc: '0.00' competition: 55 new_volume: 5316 score: 6501 _id: 2bcf4e85-860b-43eb-8d06-f82c405697e4 _index: keyword_analytics_development_20240909091534431 '/api/v1/keywords/{keyword}': get: tags: - Keywords summary: Get keyword suggestions and analytics for a specific keyword description: 'Returns paginated keyword suggestions related to a specific keyword with metrics like volume, competition, score, and CPC.' parameters: - in: path name: keyword required: true schema: type: string description: The keyword to get suggestions for - in: query name: new_volume_min schema: type: number description: Minimum new search volume - in: query name: new_volume_max schema: type: number description: Maximum new search volume - in: query name: competition_min schema: type: number description: Minimum competition score - in: query name: competition_max schema: type: number description: Maximum competition score - in: query name: score_min schema: type: number description: Minimum keyword score - in: query name: score_max schema: type: number description: Maximum keyword score - in: query name: keyword_include schema: type: string description: Include keywords containing this string - in: query name: keyword_exclude schema: type: string description: Exclude keywords containing this string - in: query name: order_by schema: type: string enum: - vol - competition - score - new_volume description: Field to sort by - in: query name: order_direction schema: type: string enum: - asc - desc default: desc description: Sort order - in: query name: page schema: type: integer default: 1 description: Page number - in: query name: per_page schema: type: integer default: 20 description: Number of results per page responses: '200': description: Successful response with keyword suggestions for the specified keyword headers: Access-Control-Allow-Origin: $ref: '#/components/headers/Access-Control-Allow-Origin' Access-Control-Allow-Headers: $ref: '#/components/headers/Access-Control-Allow-Headers' Access-Control-Allow-Methods: $ref: '#/components/headers/Access-Control-Allow-Methods' content: application/json: schema: type: object properties: current_page: type: integer example: 1 total_count: type: integer example: 3 total_pages: type: integer example: 1 results: type: array items: type: object properties: _index: type: string nullable: true example: keyword_analytics_development_20240909091534431 _id: type: string nullable: true example: f6a675cd-7e95-4543-8c31-64172ac1513d _score: type: number nullable: true example: null sort: type: array items: type: number example: 24432 keyword: type: string example: handmade jewelry vol: type: integer example: 23180 cpc: type: string example: '0.00' competition: type: number example: 102 created_at: type: string format: date-time example: '2023-04-25T13:15:23.954Z' new_volume: type: number example: 23180 score: type: number example: 24432 id: type: string example: f6a675cd-7e95-4543-8c31-64172ac1513d example: current_page: 1 total_count: 3 total_pages: 1 results: - keyword: handmade jewelry vol: 23180 cpc: '0.00' competition: 102 new_volume: 23180 score: 24432 _id: f6a675cd-7e95-4543-8c31-64172ac1513d _index: keyword_analytics_development_20240909091534431 - keyword: custom handmade jewelry vol: 23657 cpc: '0.00' competition: 679 new_volume: 23657 score: 11777.5 _id: 7ade0c78-9773-4611-aae9-58eeaa653256 _index: keyword_analytics_development_20240909091534431 - keyword: personalized handmade jewelry vol: 5316 cpc: '0.00' competition: 55 new_volume: 5316 score: 6501 _id: 2bcf4e85-860b-43eb-8d06-f82c405697e4 _index: keyword_analytics_development_20240909091534431 /api/v1/product_ideas/{product_idea}: get: tags: - Product Ideas summary: Rough go/no-go read on a product idea (spike — directional only) description: | Early, deliberately rough version of product-idea validation. Bands demand (monthly search volume) and competition (competing listing count) and returns a one-paragraph directional read. Does not yet compute revenue potential, saturation/new-entrant signals, or a formal opportunity score — those come with the full validate_product_idea design, once this spike confirms the question is worth building out. operationId: validateProductIdea parameters: - in: path name: product_idea required: true schema: type: string description: The product idea or keyword to validate, e.g. "personalized cutting board". responses: '200': description: Directional demand/competition read for the product idea. content: application/json: schema: type: object properties: summary: type: string description: Plain-language read of the idea, safe to relay to the seller verbatim. data: type: object properties: product_idea: type: string demand: type: object properties: band: type: string enum: [low, medium, high] monthly_searches: type: integer competition: type: object properties: band: type: string enum: [low, medium, high] competing_listings: type: integer meta: type: object properties: caveats: type: array items: type: string examples: default: value: summary: 'For "personalized cutting board": demand looks strong (around 14200 monthly searches), and competition looks moderate (8200 listings). This looks workable, but not a clear standout either way.' data: product_idea: personalized cutting board demand: band: high monthly_searches: 14200 competition: band: medium competing_listings: 8200 meta: caveats: - 'Rough directional read only — demand and competition bands, no revenue, saturation, or opportunity score yet.' '403': description: MCP caller is on the free Hobby plan (app calls are never refused for their plan). content: application/json: schema: type: object properties: error: type: string code: type: string