OpenMercantil Sectors API

openapi: 3.2.0
info:
  title: Openmercantil Sectors API
  contact:
    name: OpenMercantil
    url: https://openmercantil.es/soporte
    email: social@openmercantil.es
  termsOfService: https://openmercantil.es/terminos-de-uso
  x-refined-note:
  - x-account-segment-contract differs across the merged source definitions and was not carried
  - x-company-identity-contract differs across the merged source definitions and was not carried
  - x-contract-status differs across the merged source definitions and was not carried
  - x-corrections differs across the merged source definitions and was not carried
  - x-dcat-catalog differs across the merged source definitions and was not carried
  - x-language differs across the merged source definitions and was not carried
  - x-methodology differs across the merged source definitions and was not carried
  - x-publisher differs across the merged source definitions and was not carried
  - x-rate-limit differs across the merged source definitions and was not carried
  - x-sources differs across the merged source definitions and was not carried
  - x-spatial differs across the merged source definitions and was not carried
  - x-temporal differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Sectors across 2 of this provider''s published API definitions: openmercantil-openapi-1.9.3.json, openmercantil-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://openmercantil.es
  description: Production
tags:
- name: Sectors
  description: CNAE sector aggregates, ratios and company listings
paths:
  /api/v1/sector/{cnae}/companies:
    get:
      security:
      - {}
      - apiKey: []
      - bearerAuth: []
      x-api-credential-scope: companies:read
      operationId: getSectorByCnaeCompanies
      x-query-contract:
        allowed:
        - limit
        - offset
        - sort
        - province
        unknown: 400 invalid_parameter
        non_scalar: 400 invalid_parameter
        lexical: 400 invalid_parameter
        range: 422 validation_failed
        combinations: province permits only sort=recent|oldest; other documented sort values return 422
      tags:
      - Sectors
      summary: Get companies by CNAE sector code
      description: Return companies belonging to a given CNAE (Clasificación Nacional de Actividades Económicas) sector. CNAE codes 1-4 digits (eg. 62 = programación, 6201 = programación informática).
      parameters:
      - name: cnae
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9A-Z]{1,4}$
          example: '62'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 1000
          default: 0
      - name: sort
        in: query
        required: false
        description: With province only recent and oldest are accepted so the request stays index-backed.
        schema:
          type: string
          enum:
          - acts
          - recent
          - oldest
          - name
          default: acts
      - name: province
        in: query
        required: false
        schema:
          type: string
          maxLength: 80
      responses:
        '200':
          headers:
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
          description: Companies in sector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectorCompaniesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: Required sector-company index unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://openmercantil.es
      description: Production
  /api/v1/sector/{cnae}/ratios:
    get:
      security:
      - {}
      - apiKey: []
      - bearerAuth: []
      x-api-credential-scope: companies:read
      operationId: getSectorByCnaeRatios
      tags:
      - Sectors
      summary: Get sector aggregated ratios
      description: 'Return Banco de Espana Central de Balances aggregate metrics by two-digit CNAE division and year from the immutable, hash-addressed sector_ratios_public_v1 bundle. Coverage is sector-aggregate only: it contains neither individual-company data nor a company score. The endpoint fails closed with 503, without a raw/request-path fallback, when activation, manifest, file hash or public-source catalog authority cannot be verified.'
      parameters:
      - name: cnae
        in: path
        required: true
        description: Exact two-digit CNAE division present in the reviewed BdE aggregate.
        schema:
          type: string
          pattern: ^[0-9]{2}$
          minLength: 2
          maxLength: 2
      - $ref: '#/components/parameters/IfNoneMatchHeader'
      responses:
        '200':
          headers:
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
            ETag:
              $ref: '#/components/headers/EntityTag'
            Cache-Control:
              schema:
                type: string
                const: public, max-age=3600, must-revalidate
          description: Sector ratios
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectorRatiosResponse'
        '304':
          description: Not modified; the verified projection generation and legal source authority are unchanged.
          headers:
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
            ETag:
              $ref: '#/components/headers/EntityTag'
            Cache-Control:
              schema:
                type: string
                const: public, max-age=3600, must-revalidate
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/PublicReadUnavailable'
    servers:
    - url: https://openmercantil.es
      description: Production
  /api/v1/cnae/tree:
    get:
      security:
      - {}
      - apiKey: []
      - bearerAuth: []
      x-api-credential-scope: companies:read
      operationId: getCnaeTree
      tags:
      - Sectors
      summary: Hierarchical CNAE tree
      description: Return the CNAE-2009 hierarchy with counts read only from the offline sector projection. Cached 24h; no live aggregation is performed.
      x-rate-limit: plan policy (see info.x-rate-limit)
      responses:
        '200':
          headers:
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
          description: CNAE tree
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CnaeTreeResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/PublicReadUnavailable'
    servers:
    - url: https://openmercantil.es
      description: Production
  /api/v1/cnae/{code}:
    get:
      security:
      - {}
      - apiKey: []
      - bearerAuth: []
      x-api-credential-scope: companies:read
      operationId: getCnaeByCode
      tags:
      - Sectors
      summary: CNAE code metadata
      description: Return CNAE-2009 metadata and an optional company count from the offline projection. A missing projection is represented as null and never triggers a live COUNT.
      x-rate-limit: plan policy (see info.x-rate-limit)
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9A-Z]{1,4}$
          example: '6201'
      responses:
        '200':
          headers:
            X-Data-Sources:
              $ref: '#/components/headers/XDataSources'
            X-Source-Catalog-Version:
              $ref: '#/components/headers/XSourceCatalogVersion'
            X-Attribution-Required:
              $ref: '#/components/headers/XAttributionRequired'
          description: CNAE metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CnaeNode'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/PublicReadUnavailable'
    servers:
    - url: https://openmercantil.es
      description: Production
  /api/v1/sector/{code}/companies:
    get:
      tags:
      - Sectors
      summary: List Companies In A Sector
      operationId: getSectorCompanies
      description: List companies in a CNAE sector (v1.1).
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          example: '4711'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Sector companies
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound_2'
        '429':
          $ref: '#/components/responses/TooManyRequests_2'
    servers:
    - url: https://openmercantil.es
      description: Production
  /api/v1/sector/{code}/ratios:
    get:
      tags:
      - Sectors
      summary: Get Sector Financial Ratios
      operationId: getSectorRatios
      description: Return aggregated financial ratios for a CNAE sector (BdE data) (v1.1).
      parameters:
      - name: code
        in: path
        required: true
        schema:
          type: string
          example: '4711'
      responses:
        '200':
          description: Sector ratios
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '404':
          $ref: '#/components/responses/NotFound_2'
        '429':
          $ref: '#/components/responses/TooManyRequests_2'
    servers:
    - url: https://openmercantil.es
      description: Production
  /api/v1/sectores/stats:
    get:
      tags:
      - Sectors
      summary: Get Sector Aggregate Statistics
      operationId: getSectorStats
      description: Return aggregate company counts and growth statistics across CNAE sectors.
      responses:
        '200':
          description: Sector stats
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '429':
          $ref: '#/components/responses/TooManyRequests_2'
    servers:
    - url: https://openmercantil.es
      description: Production
  /api/v1/sectores/stats.csv:
    get:
      tags:
      - Sectors
      summary: Export Sector Aggregate Statistics As CSV
      operationId: getSectorStatsCsv
      description: CSV download of aggregate sector statistics.
      responses:
        '200':
          description: CSV download
          content:
            text/csv:
              schema:
                type: string
        '429':
          $ref: '#/components/responses/TooManyRequests_2'
    servers:
    - url: https://openmercantil.es
      description: Production
components:
  responses:
    ValidationFailed:
      description: The query is lexically valid but outside a documented numeric or length bound, or uses an unsupported indexed combination.
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStoreCacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStoreCacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      headers:
        Cache-Control:
          $ref: '#/components/headers/NoStoreCacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PublicReadUnavailable:
      description: The public read failed closed because its legal source catalog, subject classification, bounded projection, database helper or required artifact is unavailable. Clients must not infer an empty result.
      headers:
        Cache-Control:
          description: Unavailable public reads are never cacheable.
          schema:
            type: string
            const: no-store
        Retry-After:
          description: Optional number of seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/ProjectionUnavailableError'
            - $ref: '#/components/schemas/ErrorResponse'
          examples:
            legal_layer:
              value:
                error: legal_layer_unavailable
            company_identity:
              value:
                error: company_public_projection_unavailable
            projection:
              value:
                error: projection_unavailable
                detail: La proyección pública requerida no está disponible.
                projection: wikidata_company_v1
    TooManyRequests_2:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Maximum requests per window (60 per minute by IP on the public anonymous tier).
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Remaining requests in the current window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when the rate-limit counter resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
    NotFound_2:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
  schemas:
    SectorRatiosResponse:
      type: object
      required:
      - code
      - ratios
      properties:
        code:
          type: string
          pattern: ^[0-9]{2}$
          minLength: 2
          maxLength: 2
        ratios:
          type: array
          items:
            $ref: '#/components/schemas/SectorRatio'
      additionalProperties: false
    ProjectionUnavailableError:
      type: object
      description: Fail-closed projection outage. Clients must not reinterpret this response as an empty or negative result.
      required:
      - error
      - detail
      - projection
      properties:
        error:
          type: string
          const: projection_unavailable
        detail:
          type: string
        projection:
          type: string
      additionalProperties: false
    ErrorResponse:
      type: object
      description: Closed compatibility envelope for public/account errors. Route-specific schemas narrow these fields further where required.
      required:
      - error
      properties:
        error:
          type: string
          minLength: 1
        message:
          type: string
        detail:
          type: string
        code:
          type: string
        status:
          type:
          - integer
          - string
        projection:
          type: string
        reason:
          type: string
        source_catalog_version:
          type: string
        allowed_parameters:
          type: array
          uniqueItems: true
          items:
            type: string
        slug:
          type: string
        key:
          type: string
        maximum:
          type: integer
          minimum: 1
        parameter:
          type: string
        fields:
          type: array
          items:
            type: string
        max_bytes:
          type: integer
          minimum: 1
        allowed:
          type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        valid:
          type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        date:
          type: string
        login_url:
          type: string
        plan:
          type: string
        limited_by:
          type: string
          enum:
          - minute
          - day
        daily_limit:
          type: integer
          minimum: 1
        reset_at:
          type: integer
          minimum: 1
        reset_at_human:
          type: string
          format: date-time
        retry_after_s:
          type: integer
          minimum: 1
        retry_after:
          type: integer
          minimum: 1
        upgrade:
          type: string
          format: uri
        upgrade_url:
          type: string
        action:
          type: string
        limit:
          type: integer
          minimum: 0
        remaining:
          type: integer
          minimum: 0
        needed:
          type: integer
          minimum: 0
        shortfall:
          type: integer
          minimum: 0
        ok:
          type: boolean
        _alias_of:
          type: string
      additionalProperties: false
    CnaeNode:
      type: object
      description: CNAE node. Catalog loaders may add official explanatory fields.
      properties:
        code:
          type: string
        name:
          type: string
        level:
          type:
          - integer
          - 'null'
        parent:
          type:
          - string
          - 'null'
        companies_count:
          type:
          - integer
          - 'null'
        count_status:
          type: string
          enum:
          - precomputed
          - not_precomputed
        children:
          type: array
          items:
            $ref: '#/components/schemas/CnaeNode'
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
    SectorRatio:
      type: object
      required:
      - year
      - metric
      - value
      - unit
      - source
      properties:
        year:
          type: integer
        metric:
          type: string
          enum:
          - margen_neto
          - roa
          - roe
        value:
          type: number
        unit:
          type: string
          const: '%'
        source:
          type: string
          const: BdE Central de Balances
      additionalProperties: false
    CnaeTreeResponse:
      type: object
      required:
      - sections
      properties:
        sections:
          type: array
          items:
            $ref: '#/components/schemas/CnaeNode'
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
    JsonValue:
      description: A JSON value used only inside explicitly documented extension maps.
      oneOf:
      - type:
        - string
        - number
        - boolean
        - 'null'
      - type: array
        items:
          $ref: '#/components/schemas/JsonValue'
      - type: object
        additionalProperties:
          $ref: '#/components/schemas/JsonValue'
    SectorCompaniesResponse:
      type: object
      required:
      - code
      - count
      - count_status
      - limit
      - offset
      - sort
      - items
      properties:
        code:
          type: string
        count:
          type:
          - integer
          - 'null'
        count_status:
          type: string
          enum:
          - precomputed
          - not_precomputed
        limit:
          type: integer
        offset:
          type: integer
        sort:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/CompanySearchItem'
          maxItems: 100
      additionalProperties: false
    CompanySearchItem:
      type: object
      required:
      - slug
      - name
      - cif
      - acts_count
      properties:
        slug:
          type: string
          example: mercadona-sa
        name:
          type: string
          example: MERCADONA SA
        cif:
          type: string
          example: A46103834
        acts_count:
          type: integer
        last_seen:
          type:
          - string
          - 'null'
        province:
          type:
          - string
          - 'null'
        cnae_code:
          type:
          - string
          - 'null'
        cnae_section:
          type:
          - string
          - 'null'
        capital_cents:
          type:
          - integer
          - 'null'
          minimum: 0
        first_seen:
          type:
          - string
          - 'null'
        matched_alias:
          type: string
          description: Present only when an exact safe alias was matched; slug is always canonical.
        aliases:
          type: array
          items:
            type: string
      additionalProperties:
        $ref: '#/components/schemas/JsonValue'
    ErrorResponse_2:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      additionalProperties: true
  headers:
    EntityTag:
      description: Strong generation-bound entity tag for conditional GET.
      schema:
        type: string
        pattern: ^"[a-f0-9]{64}"$
    XSourceCatalogVersion:
      description: Mandatory on every successful public GET. Exact version of the legal source catalog used to authorize the response.
      schema:
        type: string
        minLength: 1
      example: 2026-07-12.2
    NoStoreCacheControl:
      description: Error responses must not be stored.
      schema:
        type: string
        const: no-store
    XAttributionRequired:
      description: Optional. When present, comma-separated public source aliases whose attribution terms must accompany reuse.
      schema:
        type: string
        minLength: 1
        pattern: ^[a-z0-9][a-z0-9_.-]*(,[a-z0-9][a-z0-9_.-]*)*$
      example: placsp
    XDataSources:
      description: Comma-separated aliases from the active public source catalog that contributed to the response. Omitted only when a valid exact filter returns an empty representation with zero contributing sources.
      schema:
        type: string
        minLength: 1
        pattern: ^[a-z0-9][a-z0-9_.-]*(,[a-z0-9][a-z0-9_.-]*)*$
      example: borme,placsp
  parameters:
    IfNoneMatchHeader:
      name: If-None-Match
      in: header
      required: false
      description: Optional RFC 9110 entity-tag validator. Weak validators, comma-separated validator lists and `*` are accepted.
      schema:
        type: string
        minLength: 1
        maxLength: 8192
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: ob_sess
      description: Browser session cookie set after login at /mi-cuenta/login. Mutations also require X-CSRF-Token header (obtain via GET /api/v1/user/me).
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Optional opaque omk_* API credential for public GETs. Anonymous access remains valid; a credential with the operation's x-api-credential-scope (or public:read) selects its account quota. Never place credentials in query strings.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque omk_* credential
      description: 'Optional Authorization: Bearer transport for the same opaque omk_* API credential accepted by X-API-Key. It is not a JWT or OAuth access token.'
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: Session cookie issued after web sign-in, required only for billing endpoints.
externalDocs:
  description: Documentación narrativa con ejemplos en curl/Python/JavaScript
  url: https://openmercantil.es/api/documentacion
x-refined-from:
- openmercantil-openapi-1.9.3.json
- openmercantil-openapi.yml