openapi: 3.0.0
info:
  title: Google Scholar Author API
  description: |
    The Google Scholar Author API allows you to retrieve information about academic authors, their publications, citations, co-authors, and public access mandates from Google Scholar.

    This API provides multiple views of author data:
    - **Profile View** (default): Complete author profile with publications, citations, and co-authors
    - **Citation View**: Detailed information about a specific publication
    - **Mandates View**: Public access mandate information for publications
    - **Co-authors View**: List of co-authors for an author

    **Cross-linking**: The `citation_id` returned by this API can be used with the same API to fetch detailed citation information by setting `view_op=view_citation`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Scholar Author Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["google_scholar_author"]
            default: "google_scholar_author"
        - name: author_id
          in: query
          required: false
          description: Google Scholar author ID. Required unless citation_id is provided
          schema:
            type: string
        - name: hl
          in: query
          required: false
          description: Language for the search results
          schema:
            type: string
            enum: ["af", "ak", "sq", "am", "ar", "hy", "az", "eu", "be", "bem", "bn", "bh", "xx-bork", "bs", "bt", "br", "bg", "km", "ca", "chr", "ny", "zh-cn", "zh-tw", "co", "hr", "cs", "da", "nl", "xx-elmer", "en", "eo", "et", "ee", "fo", "tl", "fi", "fr", "fy", "gaa", "gl", "ka", "de", "el", "kl", "gn", "gu", "xx-hacker", "ht", "ha", "haw", "iw", "hi", "hu", "is", "ig", "id", "ia", "ga", "it", "ja", "jw", "kn", "kk", "rw", "rn", "xx-klingon", "kg", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "loz", "lg", "ach", "mk", "mg", "my", "ms", "ml", "mt", "mv", "mi", "mr", "mfe", "mo", "mn", "sr-me", "ne", "pcm", "nso", "no", "nn", "oc", "or", "om", "ps", "fa", "xx-pirate", "pl", "pt", "pt-br", "pt-pt", "pa", "qu", "ro", "rm", "nyn", "ru", "gd", "sr", "sh", "st", "tn", "crs", "sn", "sd", "si", "sk", "sl", "so", "es", "es-419", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "to", "lua", "tum", "tr", "tk", "tw", "ug", "uk", "ur", "uz", "vu", "vi", "cy", "wo", "ws", "xh", "yi", "yo", "zu"]
            default: "en"
        - name: sortby
          in: query
          required: false
          description: Sort order for articles
          schema:
            type: string
            enum: ["pubdate", "title"]
        - name: view_op
          in: query
          required: false
          description: Type of view to retrieve
          schema:
            type: string
            enum: ["list_colleagues", "view_citation", "list_mandates", "view_mandate"]
        - name: agencyid
          in: query
          required: false
          description: Agency ID for filtering mandates
          schema:
            type: string
        - name: citation_id
          in: query
          required: false
          description: Citation ID for viewing specific citation details. Required when view_op is view_citation or view_mandate
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
      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:
      oneOf:
        - $ref: '#/components/schemas/ProfileResponse'
        - $ref: '#/components/schemas/CitationResponse'
        - $ref: '#/components/schemas/MandateResponse'
        - $ref: '#/components/schemas/MandatesListResponse'
        - $ref: '#/components/schemas/CoAuthorsResponse'

    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 Author 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"
        author_id:
          type: string
          description: "Google Scholar author ID"
        hl:
          type: string
          description: "Language for the search results"
        sortby:
          type: string
          description: "Sort order for articles"
        view_op:
          type: string
          description: "Type of view retrieved"
        agencyid:
          type: string
          description: "Agency ID for filtering mandates"
        citation_id:
          type: string
          description: "Citation ID for viewing specific citation details"
        page:
          type: integer
          description: "Page number for pagination"

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong

    ProfileResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        author:
          $ref: '#/components/schemas/Author'
        articles:
          type: array
          items:
            $ref: '#/components/schemas/Article'
        cited_by:
          $ref: '#/components/schemas/CitedBy'
        public_access:
          $ref: '#/components/schemas/PublicAccess'
        co_authors:
          type: array
          items:
            $ref: '#/components/schemas/CoAuthor'
        pagination:
          $ref: '#/components/schemas/ProfilePagination'

    Author:
      type: object
      properties:
        name:
          type: string
          description: "Author's name"
        affiliations:
          type: string
          description: "Author's affiliations"
        university:
          type: string
          description: "Author's university"
        university_authors_link:
          type: string
          description: "Link to university authors page"
        email:
          type: string
          description: "Author's email address"
        interests:
          type: array
          description: "Author's research interests"
          items:
            type: object
            properties:
              title:
                type: string
                description: "Interest title"
              link:
                type: string
                description: "Link to search for this interest"
        thumbnail:
          type: string
          description: "URL to author's profile image"

    Article:
      type: object
      properties:
        title:
          type: string
          description: "Article title"
        link:
          type: string
          description: "Link to the article"
        citation_id:
          type: string
          description: "Citation ID for fetching detailed information"
        authors:
          type: string
          description: "Article authors"
        publication:
          type: string
          description: "Publication details"
        cited_by:
          $ref: '#/components/schemas/CitedByItem'
        year:
          type: integer
          description: "Publication year"

    CitedByItem:
      type: object
      properties:
        cites_id:
          type: string
          description: "Cites ID"
        total:
          type: integer
          description: "Total number of citations"
        link:
          type: string
          description: "Link to view citations"

    CitedBy:
      type: object
      properties:
        table:
          type: object
          description: "Citation statistics table"
          additionalProperties: true
        histogram:
          type: array
          description: "Citation count by year"
          items:
            type: object
            properties:
              year:
                type: integer
                description: "Year"
              cites:
                type: integer
                description: "Number of citations"

    PublicAccess:
      type: object
      properties:
        link:
          type: string
          description: "Link to public access page"
        available:
          type: integer
          description: "Number of publicly available articles"
        not_available:
          type: integer
          description: "Number of articles not publicly available"

    CoAuthor:
      type: object
      properties:
        author_id:
          type: string
          description: "Co-author's Google Scholar ID"
        name:
          type: string
          description: "Co-author's name"
        link:
          type: string
          description: "Link to co-author's profile"
        affiliations:
          type: string
          description: "Co-author's affiliations"
        email:
          type: string
          description: "Co-author's email"
        thumbnail:
          type: string
          description: "URL to co-author's profile image"

    ProfilePagination:
      type: object
      properties:
        current:
          type: integer
          description: "Current page number"
        previous:
          type: string
          description: "URL to previous page"
        next:
          type: string
          description: "URL to next page"

    CitationResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        citation:
          $ref: '#/components/schemas/Citation'

    Citation:
      type: object
      properties:
        title:
          type: string
          description: "Citation title"
        link:
          type: string
          description: "Link to the citation"
        resources:
          type: array
          description: "Available resources"
          items:
            type: object
            properties:
              name:
                type: string
                description: "Resource name"
              format:
                type: string
                description: "Resource format"
              link:
                type: string
                description: "Link to resource"
        description:
          type: string
          description: "Citation description"
        authors:
          type: string
          description: "Citation authors"
        publication_date:
          type: string
          description: "Publication date"
        source:
          type: string
          description: "Publication source"
        volume:
          type: string
          description: "Publication volume"
        issue:
          type: string
          description: "Publication issue"
        publisher:
          type: string
          description: "Publisher name"
        pages:
          type: string
          description: "Page numbers"
        cited_by:
          $ref: '#/components/schemas/CitedByItem'
        cites_histogram:
          type: array
          description: "Citation count by year"
          items:
            type: object
            properties:
              year:
                type: integer
                description: "Year"
              cites:
                type: integer
                description: "Number of citations"
        scholar_articles:
          $ref: '#/components/schemas/ScholarArticle'

    ScholarArticle:
      type: object
      properties:
        title:
          type: string
          description: "Article title"
        link:
          type: string
          description: "Link to article"
        authors:
          type: string
          description: "Article authors"
        cited_by:
          $ref: '#/components/schemas/CitedByItem'
        versions:
          type: object
          description: "Article versions"
          additionalProperties: true
        related_articles_link:
          type: string
          description: "Link to related articles"

    MandateResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        article:
          $ref: '#/components/schemas/MandateArticle'
        mandates:
          type: array
          items:
            $ref: '#/components/schemas/Mandate'

    MandateArticle:
      type: object
      properties:
        title:
          type: string
          description: "Article title"
        link:
          type: string
          description: "Link to article"
        cluster_id:
          type: string
          description: "Google Scholar cluster ID"
        authors:
          type: string
          description: "Article authors"
        responsible_authors:
          type: string
          description: "Responsible authors for mandate"
        publication:
          type: string
          description: "Publication details"
        year:
          type: integer
          description: "Publication year"

    Mandate:
      type: object
      properties:
        title:
          type: string
          description: "Mandate title"
        link:
          type: string
          description: "Link to mandate"
        cached_page_link:
          type: string
          description: "Link to cached page"
        funding:
          type: string
          description: "Funding source"
        grant:
          type: string
          description: "Grant number"
        publicity:
          type: string
          description: "Publicity status"
        embargo:
          type: string
          description: "Embargo details"
        date:
          type: string
          description: "Mandate date"

    MandatesListResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/MandateFilter'
        author:
          $ref: '#/components/schemas/MandateAuthor'
        articles:
          type: array
          items:
            $ref: '#/components/schemas/MandateListArticle'
        pagination:
          $ref: '#/components/schemas/MandatesPagination'

    MandateFilter:
      type: object
      properties:
        title:
          type: string
          description: "Filter title"
        agencyid:
          type: string
          description: "Agency ID"
        link:
          type: string
          description: "Link to apply filter"

    MandateAuthor:
      type: object
      properties:
        author_id:
          type: string
          description: "Author's Google Scholar ID"
        name:
          type: string
          description: "Author's name"
        link:
          type: string
          description: "Link to author's profile"
        thumbnail:
          type: string
          description: "URL to author's profile image"

    MandateListArticle:
      type: object
      properties:
        title:
          type: string
          description: "Article title"
        mandate_link:
          type: string
          description: "Link to mandate details"
        citation_id:
          type: string
          description: "Citation ID"
        authors:
          type: string
          description: "Article authors"
        publication:
          type: string
          description: "Publication details"
        mandates:
          type: string
          description: "Mandate information"
        resource:
          type: object
          properties:
            name:
              type: string
              description: "Resource name"
            format:
              type: string
              description: "Resource format"
            link:
              type: string
              description: "Link to resource"
        responsible_authors:
          type: string
          description: "Responsible authors"
        year:
          type: integer
          description: "Publication year"

    MandatesPagination:
      type: object
      properties:
        current:
          type: integer
          description: "Current page number"
        previous:
          type: string
          description: "URL to previous page"
        next:
          type: string
          description: "URL to next page"
        other_pages:
          type: object
          description: "Map of page numbers to URLs"
          additionalProperties:
            type: string

    CoAuthorsResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        co_authors:
          type: array
          items:
            $ref: '#/components/schemas/CoAuthor'