MAC Address Lookup: Find Vendor, OUI & Device Type Vendors API

openapi: 3.2.0
info:
  title: macadress.com Vendors API
  version: '1.0'
  description: 'MAC address / OUI vendor lookup. Every field on the lookup response beyond the original v1 set (see the x-added-in-version extension on each) is additive and nullable: existing integrations reading only the original fields are unaffected by new ones appearing alongside them.'
  contact:
    url: https://macadress.com/docs
  license:
    name: See https://macadress.com/terms
servers:
- url: https://api.macadress.com
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: Vendors
paths:
  /v1/vendors:
    get:
      operationId: searchVendors
      summary: Search the registered vendor/block directory
      parameters:
      - name: query
        in: query
        schema:
          type: string
        description: Substring match against organization name, case-insensitive.
      - name: country
        in: query
        schema:
          type: string
        description: Exact ISO 3166-1 alpha-2 code, e.g. US, DE, JP.
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
          maximum: 50
        description: Max results to return.
      responses:
        '200':
          description: Matching non-private blocks. Counts as one call against the plan quota.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Data-Version:
              $ref: '#/components/headers/XDataVersion'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorSearchResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Vendors
components:
  headers:
    XRateLimitReset:
      description: Seconds until the current window's usage resets.
      schema:
        type: integer
    XRateLimitRemaining:
      description: Requests remaining in the current sliding window.
      schema:
        type: integer
    XDataVersion:
      description: Date (UTC) the underlying vendor database last synced successfully. Same value as meta.database_version.
      schema:
        type: string
        format: date
    XRateLimitLimit:
      description: Requests-per-minute cap for the authenticated plan.
      schema:
        type: integer
    XRequestId:
      description: Per-request identifier, present on every response including errors.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    RateLimited:
      description: Requests-per-minute limit exceeded for the authenticated plan
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    VendorSearchResult:
      type: object
      properties:
        total:
          type: integer
          description: How many blocks match
          independent of the limit applied.: null
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/VendorBlock'
    VendorBlock:
      type: object
      description: One IEEE-assigned MAC/OUI prefix block, as returned by /v1/vendors.
      properties:
        prefix_int:
          type: integer
          description: The block's registered prefix
          left-justified into the high bits of a 48-bit value.: null
        mask_bits:
          type: integer
          enum:
          - 24
          - 28
          - 36
        block_type:
          type: string
          enum:
          - MA-L
          - MA-M
          - MA-S
          - IAB
          - CID
        organization:
          type: string
        address:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2
          empty if not extracted.: null
        is_private:
          type: boolean
        first_seen_at:
          type: string
          format: date-time
        last_changed_at:
          type: string
          format: date-time
  securitySchemes:
    apiKeyHeader:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer mk_...'
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
externalDocs:
  description: Full documentation with request/response examples
  url: https://macadress.com/docs