openapi: 3.0.3
info:
  title: ShopRank API v2
  version: 2.0.0
  description: >
    API v2 enriches domains with verified e-commerce store data, including
    country, platform, category, technologies, payment providers, shipping
    carriers, contacts, VAT signals, cross-border signals, and enterprise
    merchant-size scoring fields.
  contact:
    name: ShopRank
    url: https://shoprank.com/contact
servers:
  - url: https://shoprank.com
    description: Production
tags:
  - name: Domain enrichment
    description: Lookup and enrich e-commerce domains.
  - name: Account
    description: Authentication, plan, credits, and package limits.
  - name: Reference
    description: Machine-readable field and error catalogs.
security:
  - BearerAuth: []
  - ApiKeyHeader: []
paths:
  /api/v2/domains/{domain}:
    get:
      tags:
        - Domain enrichment
      summary: Lookup one domain
      description: >
        Returns fields available on the authenticated package. The request costs
        one credit when the domain is found and zero credits when it is not found.
        Use the include query parameter to request a smaller payload.
      operationId: getDomain
      parameters:
        - name: domain
          in: path
          required: true
          description: Domain or URL to normalize and look up.
          schema:
            type: string
          examples:
            domain:
              value: aboutyou.com
            url:
              value: https://www.aboutyou.com/
        - name: include
          in: query
          required: false
          description: Comma-separated list of fields to return. Omit to return every field available on the current package.
          schema:
            type: string
          example: domain,country,country_iso,state,state_iso,city,is_ecommerce,primary_platform,tech,tech_maturity_level,estimated_monthly_tech_spend,payment_providers,shipping_carriers,social,website_year,website_month
        - name: include_meta
          in: query
          required: false
          description: Include operational metadata such as request ID, returned fields, credits, and selected freshness notes.
          schema:
            type: boolean
          example: true
      responses:
        "200":
          description: Domain lookup result.
          headers:
            X-ShopRank-API-Version:
              $ref: "#/components/headers/ApiVersion"
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
            X-Credits-Cost:
              $ref: "#/components/headers/CreditsCost"
            X-Credits-Remaining:
              $ref: "#/components/headers/CreditsRemaining"
            X-Domain-Found:
              description: Whether ShopRank found the requested domain.
              schema:
                type: string
                enum: ["true", "false"]
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Domain"
                  - $ref: "#/components/schemas/DomainNotFound"
              examples:
                found:
                  value:
                    domain: aboutyou.com
                    url: https://www.aboutyou.com/
                    country: Germany
                    country_iso: DE
                    state: Hamburg
                    state_iso: DE-HH
                    is_ecommerce: true
                    primary_platform: Custom
                    tech:
                      - Shopify
                    tech_maturity_level: Scaling
                    estimated_monthly_tech_spend: 1482
                    payment_providers:
                      - PayPal
                      - Klarna
                    shipping_carriers:
                      - DHL
                    merchant_size_score: 99
                    merchant_size_band: top_1_percent
                missing:
                  value:
                    object: domain
                    found: false
                    domain: missing.example
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/Problem"
  /api/v2/me:
    get:
      tags:
        - Account
      summary: Check API key and account limits
      description: Zero-credit endpoint for connection tests, plan checks, and credit visibility.
      operationId: getAccount
      responses:
        "200":
          description: Authenticated account state.
          headers:
            X-ShopRank-API-Version:
              $ref: "#/components/headers/ApiVersion"
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        "401":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/Problem"
  /api/v2/account:
    get:
      tags:
        - Account
      summary: Alias for /api/v2/me
      operationId: getAccountAlias
      responses:
        "200":
          description: Authenticated account state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        "401":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/Problem"
  /api/v2/fields:
    get:
      tags:
        - Reference
      summary: List API v2 fields and package availability
      description: >
        Returns the current field catalog, include presets, and plan catalog.
        Authentication is optional; when an API key is provided, current_plan is
        set for the authenticated account.
      operationId: getFields
      security: []
      responses:
        "200":
          description: Field catalog.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldsResponse"
  /api/v2/errors:
    get:
      tags:
        - Reference
      summary: List API v2 problem codes
      operationId: getErrors
      security: []
      responses:
        "200":
          description: Error catalog.
          content:
            application/json:
              schema:
                type: object
                required:
                  - api_version
                  - errors
                properties:
                  api_version:
                    type: string
                    example: v2
                  errors:
                    type: array
                    items:
                      type: object
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >
        Preferred authentication method. Use Authorization: Bearer YOUR_API_KEY.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Header-based API key authentication for no-code and workflow tools.
  headers:
    ApiVersion:
      description: ShopRank API version.
      schema:
        type: string
        example: "2"
    RequestId:
      description: Request identifier for debugging.
      schema:
        type: string
    CreditsCost:
      description: Credits charged for this request.
      schema:
        type: string
        example: "1"
    CreditsRemaining:
      description: Credits remaining after the request.
      schema:
        type: string
        example: "99"
  responses:
    Problem:
      description: API error returned as application/problem+json.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
  schemas:
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - detail
        - code
      properties:
        type:
          type: string
          format: uri
          example: "https://shoprank.com/api/v2/errors/invalid_include"
        title:
          type: string
          example: Invalid include field
        status:
          type: integer
          example: 400
        detail:
          type: string
          example: "Unknown include field: gmv_final."
        code:
          type: string
          example: invalid_include
        request_id:
          type: string
    Account:
      type: object
      properties:
        api_version:
          type: string
          example: v2
        authenticated:
          type: boolean
          example: true
        plan:
          type: string
          enum: [free, standard, premium, enterprise]
        credits_limit:
          type: integer
          nullable: true
        credits_used:
          type: integer
        credits_remaining:
          type: integer
          nullable: true
        include_presets:
          type: array
          items:
            type: object
    FieldsResponse:
      type: object
      properties:
        api_version:
          type: string
          example: v2
        auth:
          type: object
        current_plan:
          type: string
          nullable: true
        field_catalog:
          type: array
          items:
            $ref: "#/components/schemas/Field"
        include_presets:
          type: array
          items:
            type: object
        plans:
          type: array
          items:
            type: object
        errors_url:
          type: string
          format: uri
    Field:
      type: object
      required:
        - field
        - available_from
        - package
        - type
        - label
      properties:
        field:
          type: string
          example: merchant_size_score
        available_from:
          type: string
          enum: [free, standard, premium, enterprise]
        package:
          type: string
          example: Enterprise
        type:
          type: string
          example: number
        label:
          type: string
          example: Merchant size score
    DomainNotFound:
      type: object
      required:
        - object
        - found
        - domain
      properties:
        object:
          type: string
          example: domain
        found:
          type: boolean
          example: false
        domain:
          type: string
          example: missing.example
    Domain:
      type: object
      additionalProperties: false
      properties:
        domain:
          type: string
          example: aboutyou.com
        url:
          type: string
          format: uri
          nullable: true
        country:
          type: string
          nullable: true
          example: Germany
        country_iso:
          type: string
          nullable: true
          example: DE
        state:
          type: string
          nullable: true
          description: Local primary administrative subdivision, such as state, province, voivodeship, or land.
          example: Hamburg
        state_iso:
          type: string
          nullable: true
          description: ISO 3166-2 subdivision code when available.
          example: DE-HH
        city:
          type: string
          nullable: true
        text_lang:
          type: string
          nullable: true
        is_ecommerce:
          type: boolean
          nullable: true
        ecommerce_probability:
          type: number
          nullable: true
        primary_platform:
          type: string
          nullable: true
        platforms:
          type: array
          items:
            type: string
        category:
          type: string
          nullable: true
        categories:
          type: array
          items:
            type: string
        subcategory:
          type: string
          nullable: true
        subcategories:
          type: array
          items:
            type: string
        subcategory_id:
          type: string
          nullable: true
        subcategory_ids:
          type: array
          items:
            type: string
        meta_title:
          type: string
          nullable: true
        meta_description:
          type: string
          nullable: true
        tech:
          type: array
          items:
            type: string
        tech_version:
          type: array
          items:
            type: string
        premium_tech:
          type: array
          items:
            type: string
        ecommerce_plugins:
          type: array
          items:
            type: string
        tech_maturity_level:
          type: string
          nullable: true
        estimated_monthly_tech_spend:
          type: number
          nullable: true
        payment_providers:
          type: array
          items:
            type: string
        shipping_carriers:
          type: array
          items:
            type: string
        emails:
          type: array
          items:
            type: string
        phones:
          type: array
          items:
            type: string
        website_year:
          type: number
          nullable: true
        website_month:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        vat_number:
          type: string
          nullable: true
        vat_country:
          type: string
          nullable: true
        social:
          type: object
          nullable: true
          additionalProperties:
            type: string
        store_age_tier:
          type: string
          nullable: true
        first_seen_year:
          type: integer
          nullable: true
        cross_border_countries:
          type: array
          items:
            type: string
        cross_border_domains:
          type: array
          items:
            type: string
        merchant_size_score:
          type: number
          nullable: true
          description: Relative global merchant-size percentile score from 0 to 100. Higher means larger.
        merchant_size_band:
          type: string
          nullable: true
          enum: [top_1_percent, top_1_to_5_percent, top_5_to_10_percent, top_10_to_25_percent, long_tail]
        merchant_size_country_score:
          type: number
          nullable: true
          description: Relative country merchant-size percentile score from 0 to 100. Higher means larger within country.
        merchant_size_country_band:
          type: string
          nullable: true
          enum: [top_1_percent, top_1_to_5_percent, top_5_to_10_percent, top_10_to_25_percent, long_tail]
        merchant_size_confidence:
          type: string
          nullable: true
        merchant_size_source:
          type: string
          nullable: true
        cross_border_cluster_size_range:
          type: string
          nullable: true
        _meta:
          type: object
          nullable: true
