openapi: 3.0.0
info:
  title: Google Patents Details API
  description: |
    Retrieve detailed information about a specific patent or scholarly article from Google Patents.
    
    **Cross-linking**: The `patent_id` parameter can be obtained from the [Google Patents API](https://www.searchapi.io/docs/google-patents) response to fetch detailed information about a specific patent. The patent_id format is typically `patent/{PATENT_NUMBER}/{LANGUAGE_CODE}` for patents or `scholar/{SCHOLAR_ID}` for scholarly articles.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      operationId: searchGooglePatentsDetails
      summary: Google Patents Details Search
      description: Retrieve detailed information about a specific patent or scholarly article using its patent_id obtained from Google Patents search results.
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: [google_patents_details]
        - name: patent_id
          in: query
          required: true
          description: Patent or scholar identifier from Google Patents URL or search results
          schema:
            type: string
      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'
        title:
          type: string
          description: Title of the patent or document
        type:
          type: string
          description: Type of document (patent, scholarly article, etc.)
        header:
          type: string
          description: Header information for scholarly articles
        pdf:
          type: string
          description: URL to PDF version of the document
        publication_number:
          type: string
          description: Official publication number
        publication_year:
          type: string
          description: Year of publication for scholarly articles
        publication_venue:
          type: string
          description: Publication venue for scholarly articles
        full_view_url:
          type: string
          description: URL to full view of scholarly article
        institution_url:
          type: string
          description: Institution URL for scholarly articles
        cited_by_url:
          type: string
          description: URL to cited by information
        main_url:
          type: string
          description: Main URL of the document
        other_versions_url:
          type: string
          description: URL to other versions
        country:
          type: string
          description: Country of patent registration
        prior_art_keywords:
          type: array
          items:
            type: string
          description: Keywords related to prior art
        prior_art_date:
          type: string
          description: Date of prior art
        application_number:
          type: string
          description: Patent application number
        inventors:
          type: array
          items:
            $ref: '#/components/schemas/Inventor'
          description: List of inventors
        assignees:
          type: array
          items:
            type: string
          description: List of current assignees
        authors:
          type: array
          items:
            type: string
          description: List of authors for scholarly articles
        priority_year:
          type: string
          description: Priority year
        priority_date:
          type: string
          description: Priority date
        filing_date:
          type: string
          description: Filing date
        publication_date:
          type: string
          description: Publication date
        worldwide_applications:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/WorldwideApplication'
          description: Worldwide applications organized by year
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: Timeline of patent events
        external_links:
          type: array
          items:
            $ref: '#/components/schemas/ExternalLink'
          description: External links related to the patent
        images:
          type: array
          items:
            type: string
          description: URLs of patent images
        classifications:
          type: array
          items:
            $ref: '#/components/schemas/Classification'
          description: Patent classifications
        abstract:
          type: string
          description: Abstract of the patent or document
        abstract_original:
          type: string
          description: Original language abstract
        snippet:
          type: string
          description: Brief snippet of the document
        description:
          type: string
          description: Full description of the patent
        claims:
          type: array
          items:
            type: string
          description: Patent claims
        child_applications:
          type: array
          items:
            $ref: '#/components/schemas/RelatedApplication'
          description: Child applications derived from this patent
        parent_applications:
          type: array
          items:
            $ref: '#/components/schemas/RelatedApplication'
          description: Parent applications this patent is derived from
        priority_applications:
          type: array
          items:
            $ref: '#/components/schemas/RelatedApplication'
          description: Priority applications
        applications_claiming_priority:
          type: array
          items:
            $ref: '#/components/schemas/RelatedApplication'
          description: Applications claiming priority from this patent
        patent_citations:
          $ref: '#/components/schemas/CitationGroup'
        non_patent_citations:
          type: array
          items:
            $ref: '#/components/schemas/NonPatentCitation'
          description: Non-patent literature citations
        cited_by:
          $ref: '#/components/schemas/CitationGroup'
        similar_documents:
          type: array
          items:
            $ref: '#/components/schemas/SimilarDocument'
          description: Similar documents
        legal_events:
          type: array
          items:
            $ref: '#/components/schemas/LegalEvent'
          description: Legal events related to the patent
        concepts:
          $ref: '#/components/schemas/Concepts'
    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 Patents 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
        patent_id:
          type: string
          description: Patent ID used for the search
    Inventor:
      type: object
      properties:
        name:
          type: string
          description: Name of the inventor
        link:
          type: string
          description: Link to inventor's other patents
    WorldwideApplication:
      type: object
      properties:
        filing_date:
          type: string
          description: Filing date of the application
        country_code:
          type: string
          description: Country code
        application_number:
          type: string
          description: Application number
        document_id:
          type: string
          description: Document identifier
        legal_status_cat:
          type: string
          description: Legal status category
        legal_status:
          type: string
          description: Detailed legal status
        link:
          type: string
          description: Link to the application
    Event:
      type: object
      properties:
        date:
          type: string
          description: Date of the event
        title:
          type: string
          description: Title of the event
        type:
          type: string
          description: Type of event
        critical:
          type: boolean
          description: Whether this is a critical event
        current:
          type: boolean
          description: Whether this is the current status
        assignee_search:
          type: string
          description: Assignee information for search
        external_link:
          type: string
          description: External link related to the event
        description:
          type: array
          items:
            type: string
          description: Detailed description of the event
        document_id:
          type: string
          description: Document ID associated with the event
    ExternalLink:
      type: object
      properties:
        text:
          type: string
          description: Display text for the link
        link:
          type: string
          description: External URL
    Classification:
      type: object
      properties:
        code:
          type: string
          description: Classification code
        description:
          type: string
          description: Description of the classification
        leaf:
          type: boolean
          description: Whether this is a leaf classification
        first_code:
          type: boolean
          description: Whether this is the first/primary classification
        is_cpc:
          type: boolean
          description: Whether this is a CPC classification
    RelatedApplication:
      type: object
      properties:
        application_number:
          type: string
          description: Application number
        relation_type:
          type: string
          description: Type of relationship to the current patent
        representative_publication:
          type: string
          description: Representative publication number
        primary_language:
          type: string
          description: Primary language
        priority_date:
          type: string
          description: Priority date
        filing_date:
          type: string
          description: Filing date
        title:
          type: string
          description: Title of the application
        link:
          type: string
          description: Link to the application
    CitationGroup:
      type: object
      properties:
        original:
          type: array
          items:
            $ref: '#/components/schemas/PatentCitation'
          description: Original citations
        family_to_family:
          type: array
          items:
            $ref: '#/components/schemas/PatentCitation'
          description: Family to family citations
    PatentCitation:
      type: object
      properties:
        publication_number:
          type: string
          description: Publication number of cited patent
        primary_language:
          type: string
          description: Primary language of the cited patent
        priority_date:
          type: string
          description: Priority date
        publication_date:
          type: string
          description: Publication date
        assignee_original:
          type: string
          description: Original assignee
        title:
          type: string
          description: Title of cited patent
        patent_id:
          type: string
          description: Patent ID for linking to details
        link:
          type: string
          description: Full URL to the cited patent
    NonPatentCitation:
      type: object
      properties:
        title:
          type: string
          description: Title of the cited work
        link:
          type: string
          description: Link to the cited work
    SimilarDocument:
      type: object
      properties:
        is_patent:
          type: boolean
          description: Whether this is a patent document
        is_scholar:
          type: boolean
          description: Whether this is a scholarly article
        publication_number:
          type: string
          description: Publication number
        primary_language:
          type: string
          description: Primary language of the document
        publication_date:
          type: string
          description: Publication date
        title:
          type: string
          description: Title of similar document
        scholar_authors:
          type: string
          description: Authors for scholarly articles
        scholar_id:
          type: string
          description: Scholar ID for scholarly articles
        patent_id:
          type: string
          description: Patent ID for linking to details
        link:
          type: string
          description: Link to similar document
    LegalEvent:
      type: object
      properties:
        date:
          type: string
          description: Date of legal event
        code:
          type: string
          description: Legal event code
        title:
          type: string
          description: Title of legal event
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/LegalEventAttribute'
          description: Additional attributes of the legal event
    LegalEventAttribute:
      type: object
      properties:
        label:
          type: string
          description: Attribute label
        value:
          type: string
          description: Attribute value
    Concepts:
      type: object
      properties:
        match:
          type: array
          items:
            $ref: '#/components/schemas/Concept'
          description: Matched concepts
    Concept:
      type: object
      properties:
        id:
          type: string
          description: Concept identifier
        name:
          type: string
          description: Concept name
        domain:
          type: string
          description: Domain of the concept
        similarity:
          type: number
          description: Similarity score
        sections:
          type: array
          items:
            type: string
          description: Sections where the concept appears
        count:
          type: integer
          description: Count of concept occurrences
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong