IsraBase Search API

openapi: 3.2.0
info:
  title: IsraBase Search API
  version: 1.0.0
  contact:
    name: IsraBase
    url: https://israbase.com/developers
    email: api@israbase.com
  license:
    name: 'Data: data.gov.il open data'
    url: https://data.gov.il
  x-logo:
    url: https://israbase.com/icon.svg
    altText: IsraBase
  summary: Israeli companies, nonprofits, partnerships and the business-for-sale board.
  description: 'Read-only JSON API for the IsraBase registry (ישראבייס). Data comes from data.gov.il. Credit IsraBase and data.gov.il when you reuse it. Anonymous clients: 5 requests per minute and 50 per UTC day. A free API key: 5 per minute and 50 per UTC day. Send the key as Authorization: Bearer or as X-API-Key. A key is optional. A free key uses the same limits. Request a free key at https://israbase.com/developers/key. For a higher quota, write to api@israbase.com. Query q is at most 100 characters. Query limit is at most 100, except marketplace listings which allow at most 50. A 401, a 429, and a response to a request with an API key include RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Those responses are Cache-Control: private, no-store. An anonymous 200 may be cached and does not include those counters. A 429 response also includes Retry-After.'
servers:
- url: https://israbase.com
security:
- bearerAuth: []
- apiKeyHeader: []
- {}
tags:
- name: Search
paths:
  /api/v1/search:
    get:
      operationId: searchCompanies
      summary: Search companies by name or number
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 100
        description: Name or company number.
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 200000
          default: 0
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
        description: 1-based page. Do not send page and offset together.
      - name: city
        in: query
        schema:
          type: string
          maxLength: 80
        description: Optional. Exact Hebrew city name. Visible companies only.
      - name: status
        in: query
        schema:
          type: string
          maxLength: 80
        description: Optional. Exact Hebrew company status.
      - name: type
        in: query
        schema:
          type: string
          enum:
          - government
          - public
          - foreign
          - bonds
        description: Optional company segment.
      responses:
        '200':
          description: Matching visible companies. Each row includes url and nesach_url. Filters and offset are echoed when used.
          content:
            application/json:
              example:
                query: טבע
                count: 1
                data:
                - company_number: 520013954
                  name_he: טבע
                  url: https://israbase.com/company/520013954
        '400':
          description: Missing q, q longer than 100, bad limit, bad offset, or an unknown type
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - Search
components:
  schemas:
    ErrorObject:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            retry_after:
              type: integer
              description: Seconds. Present when code is rate_limited.
    RateLimited:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - retry_after
          properties:
            code:
              const: rate_limited
            message:
              type: string
              examples:
              - Rate limit exceeded. Retry after 12 seconds.
            retry_after:
              type: integer
              examples:
              - 12
  responses:
    TooManyRequests:
      description: Minute or UTC-day quota exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the client may retry.
        RateLimit-Limit:
          schema:
            type: integer
        RateLimit-Remaining:
          schema:
            type: integer
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until this window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimited'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded. Retry after 12 seconds.
              retry_after: 12
    Unauthorized:
      description: The API key is missing a match, empty, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorObject'
          example:
            error:
              code: invalid_api_key
              message: Invalid API key.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Optional free API key. An invalid key returns 401.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Optional API key. Same key as bearerAuth.