compsniper-com Mercari API

openapi: 3.2.0
info:
  title: CompSniper Marketplace and Shipping Mercari API
  version: 2.3.0
  description: Public eBay (including up to 3 years of sold history), Poshmark, Mercari, TCGplayer, Grailed, Depop and PSA graded card (prices by grade, population) data plus a separate quote-only US shipping-rates product. Shipping quotes separate applicable services from carrier-packaging and content-restricted options, use an independent subscription and quota, and do not consume sold-comps requests or purchased credits.
  contact:
    name: CompSniper
    url: https://compsniper.com
servers:
- url: https://api.compsniper.com
security:
- bearerAuth: []
tags:
- name: Mercari
paths:
  /v1/mercari:
    get:
      tags:
      - Mercari
      summary: Search Mercari sold or active listings
      description: Returns one page of public Mercari sold or active listings through a managed anonymous guest session. Authentication, rate limits, monthly quota, purchased credits, request IDs, and cache headers match the other CompSniper endpoints. Each successful page uses one CompSniper request and returns up to 100 items.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - schema:
          type: string
          minLength: 1
          description: Mercari search term
          example: pokemon cards
        required: true
        name: keyword
        in: query
      - schema:
          type: integer
          minimum: 1
          default: 1
          description: Page number, maps to offset = (page - 1) * count
          example: 1
        required: false
        name: page
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          description: Items per page (max 100)
          example: 100
        required: false
        name: count
        in: query
      - schema:
          type: string
          enum:
          - bestMatch
          - newest
          - lowestPrice
          - highestPrice
          - recentlySold
          - mostPopular
          default: bestMatch
          description: Sort order. recentlySold maps to Mercari's current Recently sold option. mostPopular is accepted as a compatibility alias for recentlySold.
        required: false
        name: sortOrder
        in: query
        description: Sort order. recentlySold maps to Mercari's current Recently sold option. mostPopular is accepted as a compatibility alias for recentlySold.
      - schema:
          type:
          - number
          - 'null'
          minimum: 0
          description: Minimum price filter in dollars
          example: 10
        required: false
        name: minPrice
        in: query
      - schema:
          type:
          - number
          - 'null'
          minimum: 0
          description: Maximum price filter in dollars
          example: 100
        required: false
        name: maxPrice
        in: query
      - schema:
          type: string
          enum:
          - any
          - new
          - likeNew
          - good
          - fair
          - poor
          default: any
          description: Condition filter
        required: false
        name: itemCondition
        in: query
      - schema:
          type: string
          description: Mercari category ID
        required: false
        name: categoryId
        in: query
      - schema:
          type: string
          description: Mercari brand ID
        required: false
        name: brandId
        in: query
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'true'
          description: true = sold listings (default), false = active listings
          example: 'true'
        required: false
        name: sold
        in: query
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
          description: 'true = add listedAt (the date Mercari shows as "Posted", ISO 8601 UTC) to each result. Slower: each listing is looked up separately. null when a date cannot be read.'
          example: 'true'
        required: false
        name: includeListedAt
        in: query
      responses:
        '200':
          description: Mercari listings
          content:
            application/json:
              schema:
                type: object
                properties:
                  keyword:
                    type: string
                  page:
                    type: number
                  count:
                    type: number
                  totalResults:
                    type: number
                  totalItems:
                    type: number
                  hasNextPage:
                    type: boolean
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        itemId:
                          type: string
                        url:
                          type: string
                        title:
                          type: string
                        price:
                          type: string
                          description: Dollars, 2 decimal places
                          example: '25.00'
                        currency:
                          type: string
                          enum:
                          - USD
                        originalPrice:
                          type:
                          - string
                          - 'null'
                        condition:
                          type:
                          - string
                          - 'null'
                        conditionId:
                          type:
                          - number
                          - 'null'
                        status:
                          type: string
                          enum:
                          - sold
                          - active
                        imageUrl:
                          type:
                          - string
                          - 'null'
                        thumbnailUrl:
                          type:
                          - string
                          - 'null'
                        sellerId:
                          oneOf:
                          - type: integer
                          - type: string
                        brand:
                          type:
                          - string
                          - 'null'
                        categoryId:
                          type:
                          - number
                          - 'null'
                        categoryName:
                          type:
                          - string
                          - 'null'
                        marketplace:
                          type: string
                          enum:
                          - mercari
                      required:
                      - itemId
                      - url
                      - title
                      - price
                      - currency
                      - originalPrice
                      - condition
                      - conditionId
                      - status
                      - imageUrl
                      - thumbnailUrl
                      - sellerId
                      - brand
                      - categoryId
                      - categoryName
                      - marketplace
                  marketplace:
                    type: string
                    enum:
                    - mercari
                  scrapedAt:
                    type: string
                  summary:
                    allOf:
                    - $ref: '#/components/schemas/PriceSummary'
                required:
                - keyword
                - page
                - count
                - totalResults
                - totalItems
                - hasNextPage
                - items
                - marketplace
                - scrapedAt
                - summary
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
                required:
                - error
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    code:
                      type: string
                      enum:
                      - rate_limited
                    error:
                      type: string
                    plan:
                      type: string
                    limit:
                      type: number
                    remaining:
                      type: number
                      enum:
                      - 0
                    retry_after:
                      type: number
                    reset:
                      type: number
                  required:
                  - code
                  - error
                  - plan
                  - limit
                  - remaining
                  - retry_after
                  - reset
                - type: object
                  properties:
                    code:
                      type: string
                      enum:
                      - quota_exceeded
                    error:
                      type: string
                    plan:
                      type: string
                    limit:
                      type: number
                    used:
                      type: number
                    remaining:
                      type: number
                      enum:
                      - 0
                    reset_at:
                      type: string
                    retry_after:
                      type: number
                    upgrade_url:
                      type: string
                  required:
                  - code
                  - error
                  - plan
                  - limit
                  - used
                  - remaining
                  - reset_at
                  - retry_after
                  - upgrade_url
        '500':
          description: Search failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
                required:
                - error
        '502':
          description: mercari-api fetch failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
                required:
                - error
        '503':
          description: Temporary Mercari connection failure (upstream_unavailable) or exhausted search capacity (server_busy). Failed requests do not consume allowance. Retry after the Retry-After delay.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Request-ID:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: searchMercariListings
components:
  parameters:
    CreditSource:
      name: X-Credit-Source
      in: header
      required: false
      schema:
        type: string
        enum:
        - credits
      description: Omit to use temporary carryover first, then monthly quota, then purchased credits. Set to credits to spend a purchased credit directly. Failed searches are not charged.
  schemas:
    PriceSummary:
      type:
      - object
      - 'null'
      description: Deterministic price intelligence over the returned sold items.
      properties:
        count:
          type: integer
          description: Items with a usable sold price.
        currency:
          type:
          - string
          - 'null'
        median:
          type: number
        mean:
          type: number
        min:
          type: number
        max:
          type: number
        p25:
          type: number
          description: Lower bound of the realistic range.
        p75:
          type: number
          description: Upper bound of the realistic range.
        avgShipping:
          type:
          - number
          - 'null'
    ApiError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        retry_after:
          type: integer
          description: Seconds before a temporary rate_limited request may be retried.
        reset_at:
          type: string
          format: date-time
          description: Billing-cycle reset for quota_exceeded.
        plan:
          type: string
        quota:
          type: integer
        used:
          type: integer
        remaining:
          type: integer
        rollover_balance:
          type: integer
          description: Temporary carried-over requests remaining.
        upgrade_url:
          type: string
          format: uri
          description: Plan-management URL for quota_exceeded.
        credit_balance:
          type: integer
          description: Non-expiring purchased credits remaining.
        purchase_credits_url:
          type: string
          format: uri
          description: Credit purchase URL for quota_exceeded.
        subscription_url:
          type: string
          format: uri
          description: Shipping Rates plan URL for shipping_subscription_required or shipping_quota_exceeded.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your API key as ''Authorization: Bearer cs_live_...''.'