openapi: 3.0.0
info:
  title: Google Scholar Case Law API
  description: |
    The Google Scholar Case Law API returns the full opinion of a US federal or state court case indexed by Google Scholar, identified by its `caselaw_id`. A single response includes the case header (title, full party name, court, first/last page), every reporter citation, the docket numbers, every cited case grouped by case ID with each textual appearance preserved, every footnote split apart from the body, and the cleaned full text of the opinion.

    **Cross-linking**: The `caselaw_id` value can be obtained from the `organic_results.caselaw_id` field returned by the Google Scholar API when searching in case-law mode (set the `as_sdt` parameter), or from the `referenced_cases.caselaw_id` field of any other Google Scholar Case Law response — chaining cases together for citation-graph traversal.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Scholar Case Law Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use.
          schema:
            type: string
            enum: ["google_scholar_case_law"]
        - name: caselaw_id
          in: query
          required: true
          description: Numeric Google Scholar case identifier. Obtain it from the `organic_results.caselaw_id` field of a Google Scholar API response in case-law mode, or from the `referenced_cases.caselaw_id` field of any other Google Scholar Case Law response.
          schema:
            type: string
            pattern: '^\d+$'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        case_information:
          $ref: '#/components/schemas/CaseInformation'
        reporter_citations:
          type: array
          description: Reporter citations for this case (e.g. "33 N.Y.3d 336 (2019)").
          items:
            $ref: '#/components/schemas/ReporterCitation'
        dates:
          type: array
          description: Dates the case progressed through (Argued, Decided, Reargued, Amended, etc.).
          items:
            $ref: '#/components/schemas/DateEntry'
        docket_numbers:
          type: array
          description: Court-assigned docket numbers for the case.
          items:
            $ref: '#/components/schemas/DocketNumber'
        referenced_cases:
          type: array
          description: Other cases referenced within the opinion, grouped by case ID with each textual appearance preserved.
          items:
            $ref: '#/components/schemas/ReferencedCase'
        footnotes:
          type: array
          description: Footnotes referenced within the opinion, extracted as a structured array.
          items:
            $ref: '#/components/schemas/Footnote'
        full_text:
          type: string
          description: Cleaned full opinion text with paragraph structure preserved. Inline `[N]` markers cross-reference into `footnotes`.
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "Google Scholar URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used.
        caselaw_id:
          type: string
          description: Case identifier echoed from the request.
    CaseInformation:
      type: object
      required: [caselaw_id, title, name, court]
      properties:
        caselaw_id:
          type: string
          description: Numeric Google Scholar case identifier.
        title:
          type: string
          description: Short title of the case as displayed by Scholar (e.g. "Brown v. Board of Education, 347 US 483 - Supreme Court 1954").
        name:
          type: string
          description: Full party name as it appears in the official report.
        court:
          type: string
          description: Name of the court that issued the opinion.
        first_page:
          type: integer
          description: First page of the opinion in its reporter volume.
        last_page:
          type: integer
          description: Last page of the opinion in its reporter volume.
    ReporterCitation:
      type: object
      required: [position, text]
      properties:
        position:
          type: integer
          description: Position of the citation within the case header.
        text:
          type: string
          description: Reporter citation string (e.g. "33 N.Y.3d 336 (2019)", "126 N.E.3d 1041", "1 Cranch 137").
    DateEntry:
      type: object
      required: [position, date, type]
      properties:
        position:
          type: integer
          description: Position of this date entry in the case header.
        date:
          type: string
          description: Calendar date as it appears on the page (e.g. "December 9, 1952").
        type:
          type: string
          description: Type of date entry (e.g. "Argued", "Reargued", "Decided", "Amended", "Filed", "Submitted").
    DocketNumber:
      type: object
      required: [position, number]
      properties:
        position:
          type: integer
          description: Position of this docket number in the case header.
        number:
          type: string
          description: Docket number as assigned by the court (e.g. "1", "21", "09-2622-cv").
    ReferencedCase:
      type: object
      required: [position, caselaw_id, link, citations]
      properties:
        position:
          type: integer
          description: Order of first appearance within the opinion.
        caselaw_id:
          type: string
          description: Numeric Google Scholar identifier of the referenced case. Pass back into this API to retrieve the referenced case's full opinion.
        link:
          type: string
          description: Google Scholar URL to the referenced case.
        citations:
          type: array
          description: Distinct case-name forms under which this case is referenced in the opinion. Each entry groups every textual variation (full first cite, "supra", short pinpoint cites) that share the same case name.
          items:
            $ref: '#/components/schemas/Citation'
    Citation:
      type: object
      required: [cite_name, variations]
      properties:
        cite_name:
          type: string
          description: Case-name form under which the referenced case appears (e.g. "Plessy" for SCOTUS-style cites where defendant is split, or the full "X v Y" form for state-style cites with no period after "v").
        variations:
          type: array
          description: Each textual appearance of this cite_name within the opinion, preserved verbatim.
          items:
            $ref: '#/components/schemas/CitationVariation'
    CitationVariation:
      type: object
      required: [position, text]
      properties:
        position:
          type: integer
          description: Order of appearance among variations sharing the same cite_name.
        defendant:
          type: string
          description: Defendant party name, when the citation uses SCOTUS-style "v." (with period) and is cleanly splittable.
        text:
          type: string
          description: Verbatim text of this citation as it appears in the opinion (e.g. "Plessy v. Ferguson, 163 U. S. 537" or "Plessy v. Ferguson, supra").
    Footnote:
      type: object
      required: [position, marker, text]
      properties:
        position:
          type: integer
          description: Sequential position of this footnote in the case.
        marker:
          type: string
          description: Bracketed marker as displayed in the opinion (e.g. "[*]", "[1]", "[14]"). Matches the inline `[N]` markers retained in `full_text`.
        text:
          type: string
          description: Body text of the footnote with paragraph structure preserved.
        links:
          type: array
          description: Cited cases or external resources linked from inside this footnote, in the order they appear. Omitted when the footnote contains no anchors.
          items:
            $ref: '#/components/schemas/FootnoteLink'
    FootnoteLink:
      type: object
      required: [text, link]
      properties:
        text:
          type: string
          description: Anchor text as displayed in the footnote (typically the verbatim citation).
        link:
          type: string
          description: Absolute URL of the linked resource.
        caselaw_id:
          type: string
          description: Numeric Google Scholar case identifier, when the link points at another scholar_case opinion. Reuse it as the `caselaw_id` parameter to fetch that case. Omitted for non-scholar links.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong.