Studio Ghibli API

openapi: 3.0.3
info:
  title: Studio Ghibli API
  description: |
    The Studio Ghibli API catalogs the people, places, and things found in the worlds of Studio Ghibli. It is an unofficial, fan-made, community-built REST API that exposes five resource collections: films, people, locations, species, and vehicles. Resources are returned as JSON and cross-link to each other through their canonical URLs, so consumers can traverse the graph (e.g. fetch a film, then its people, then their species) without authentication.

    The original API was hosted at `ghibliapi.herokuapp.com`; after Heroku's free tier ended in November 2022 the canonical instance was archived and moved to `ghibliapi.vercel.app`. Source: https://github.com/janaipakos/ghibliapi (MIT, archived 2022-12-02).
  version: 1.0.1
  license:
    name: MIT
    url: https://github.com/janaipakos/ghibliapi/blob/master/LICENSE
  contact:
    name: Studio Ghibli API (community-maintained)
    url: https://github.com/janaipakos/ghibliapi
  x-generated-from: documentation
  x-source-spec: https://raw.githubusercontent.com/janaipakos/ghibliapi/master/public/swagger.yaml
  x-last-validated: '2026-05-29'
servers:
  - url: https://ghibliapi.vercel.app
    description: Current canonical instance (Vercel)
  - url: https://ghibliapi.herokuapp.com
    description: Legacy instance (Heroku free tier ended 2022-11-28; may be unavailable)
tags:
  - name: Films
    description: Studio Ghibli theatrical films.
  - name: People
    description: Characters that appear in Studio Ghibli films.
  - name: Locations
    description: Settings and places that appear in Studio Ghibli films.
  - name: Species
    description: Species classifications of characters appearing in Studio Ghibli films.
  - name: Vehicles
    description: Vehicles featured in Studio Ghibli films.
paths:
  /films:
    get:
      operationId: listFilms
      summary: List Films
      description: Return all Studio Ghibli films catalogued by the API.
      tags:
        - Films
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: An array of films.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Film'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /films/{id}:
    get:
      operationId: getFilm
      summary: Get Film By Id
      description: Return a single film identified by its UUID.
      tags:
        - Films
      parameters:
        - $ref: '#/components/parameters/FilmId'
        - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: A single film resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Film'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /people:
    get:
      operationId: listPeople
      summary: List People
      description: Return all the people from across the Studio Ghibli universe.
      tags:
        - People
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: An array of people.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Person'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /people/{id}:
    get:
      operationId: getPerson
      summary: Get Person By Id
      description: Return a single character identified by its UUID.
      tags:
        - People
      parameters:
        - $ref: '#/components/parameters/PersonId'
        - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: A single person resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /locations:
    get:
      operationId: listLocations
      summary: List Locations
      description: Return all the locations that have appeared in the Studio Ghibli films.
      tags:
        - Locations
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: An array of locations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /locations/{id}:
    get:
      operationId: getLocation
      summary: Get Location By Id
      description: Return a single location identified by its UUID.
      tags:
        - Locations
      parameters:
        - $ref: '#/components/parameters/LocationId'
        - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: A single location resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /species:
    get:
      operationId: listSpecies
      summary: List Species
      description: Return all the species (human and non-human) that appear in the Studio Ghibli films.
      tags:
        - Species
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: An array of species.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Species'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /species/{id}:
    get:
      operationId: getSpecies
      summary: Get Species By Id
      description: Return a single species identified by its UUID.
      tags:
        - Species
      parameters:
        - $ref: '#/components/parameters/SpeciesId'
        - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: A single species resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Species'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vehicles:
    get:
      operationId: listVehicles
      summary: List Vehicles
      description: Return all the vehicles that have been used in the Studio Ghibli films.
      tags:
        - Vehicles
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: An array of vehicles.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Vehicle'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vehicles/{id}:
    get:
      operationId: getVehicle
      summary: Get Vehicle By Id
      description: Return a single vehicle identified by its UUID.
      tags:
        - Vehicles
      parameters:
        - $ref: '#/components/parameters/VehicleId'
        - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: A single vehicle resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vehicle'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    Fields:
      name: fields
      in: query
      description: Comma-separated list of fields to include in the response. When omitted, all fields are returned.
      required: false
      schema:
        type: string
      example: title,director,release_date
    Limit:
      name: limit
      in: query
      description: Number of results to return. Default is 50; maximum is 250.
      required: false
      schema:
        type: integer
        format: int32
        default: 50
        minimum: 1
        maximum: 250
      example: 50
    FilmId:
      name: id
      in: path
      description: The UUID of the film.
      required: true
      schema:
        type: string
        format: uuid
      example: 58611129-2dbc-4a81-a72f-77ddfc1b1b49
    PersonId:
      name: id
      in: path
      description: The UUID of the person.
      required: true
      schema:
        type: string
        format: uuid
      example: 267649ac-fb1b-11eb-9a03-0242ac130003
    LocationId:
      name: id
      in: path
      description: The UUID of the location.
      required: true
      schema:
        type: string
        format: uuid
      example: 11014596-71b0-4b3e-b8c0-1c4b15f28b9a
    SpeciesId:
      name: id
      in: path
      description: The UUID of the species.
      required: true
      schema:
        type: string
        format: uuid
      example: af3910a6-429f-4c74-9ad5-dfe1c4aa04f2
    VehicleId:
      name: id
      in: path
      description: The UUID of the vehicle.
      required: true
      schema:
        type: string
        format: uuid
      example: 4e09b023-f650-4747-9ab9-eacf14540cfb
  responses:
    BadRequest:
      description: Bad request — the query parameters or path identifier could not be parsed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found — no resource matches the supplied identifier.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Film:
      type: object
      description: A Studio Ghibli theatrical film.
      required: [id, title, description, director, producer, release_date]
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier representing a specific film.
          example: 2baf70d1-42bb-4437-b551-e5fed5a87abe
        title:
          type: string
          description: Title of the film in English.
          example: Castle in the Sky
        original_title:
          type: string
          description: Original Japanese title of the film (in Japanese characters).
          example: 天空の城ラピュタ
        original_title_romanised:
          type: string
          description: Original Japanese title romanised in Latin characters.
          example: Tenkū no shiro Rapyuta
        image:
          type: string
          format: uri
          description: URL of the film poster image.
        movie_banner:
          type: string
          format: uri
          description: URL of the film banner image.
        description:
          type: string
          description: Plot summary or synopsis of the film.
        director:
          type: string
          description: Director of the film.
          example: Hayao Miyazaki
        producer:
          type: string
          description: Producer of the film.
          example: Isao Takahata
        release_date:
          type: string
          description: Original theatrical release year (YYYY).
          example: '1986'
        running_time:
          type: string
          description: Running time of the film in minutes.
          example: '124'
        rt_score:
          type: string
          description: Rotten Tomatoes critical score.
          example: '95'
        people:
          type: array
          description: People that appear in or are associated with the film.
          items:
            type: string
            format: uri
        species:
          type: array
          description: Species that appear in or are associated with the film.
          items:
            type: string
            format: uri
        locations:
          type: array
          description: Locations that appear in or are associated with the film.
          items:
            type: string
            format: uri
        vehicles:
          type: array
          description: Vehicles that appear in or are associated with the film.
          items:
            type: string
            format: uri
        url:
          type: string
          format: uri
          description: Canonical URL of the film resource.
    Person:
      type: object
      description: A character that appears in one or more Studio Ghibli films.
      required: [id, name]
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier representing a specific person.
          example: 267649ac-fb1b-11eb-9a03-0242ac130003
        name:
          type: string
          description: Name of the character.
          example: Haku
        gender:
          type: string
          description: The character's gender as portrayed in the film(s).
          example: Male
        age:
          type: string
          description: The character's age. May be a number, a range, or descriptive (e.g. "unknown").
          example: '12'
        eye_color:
          type: string
          description: The character's eye colour.
          example: Green
        hair_color:
          type: string
          description: The character's hair colour.
          example: Green
        films:
          type: array
          description: Films in which this character appears.
          items:
            type: string
            format: uri
        species:
          type: string
          format: uri
          description: Species of the character (URL reference).
        url:
          type: string
          format: uri
          description: Canonical URL of the person resource.
    Location:
      type: object
      description: A setting or place that appears in Studio Ghibli films.
      required: [id, name]
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier representing a specific location.
          example: 11014596-71b0-4b3e-b8c0-1c4b15f28b9a
        name:
          type: string
          description: Name of the location.
          example: Irontown
        climate:
          type: string
          description: Predominant climate of the location.
          example: Continental
        terrain:
          type: string
          description: Predominant terrain of the location.
          example: Mountain
        surface_water:
          type: string
          description: Approximate percentage of the location covered by surface water.
          example: '40'
        residents:
          type: array
          description: People who reside at this location.
          items:
            type: string
            format: uri
        films:
          type: array
          description: Films in which this location appears.
          items:
            type: string
            format: uri
        url:
          type: string
          format: uri
          description: Canonical URL of the location resource.
    Species:
      type: object
      description: A species classification of a character or creature in the Studio Ghibli films.
      required: [id, name]
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier representing a specific species.
          example: af3910a6-429f-4c74-9ad5-dfe1c4aa04f2
        name:
          type: string
          description: Common name of the species.
          example: Human
        classification:
          type: string
          description: Biological classification (e.g. Mammal, Spirit, Cat).
          example: Mammal
        eye_colors:
          type: string
          description: Comma-separated list of eye colours observed within the species.
          example: Black, Blue, Brown, Grey, Green, Hazel
        hair_colors:
          type: string
          description: Comma-separated list of hair colours observed within the species.
          example: Black, Blonde, Brown, Grey, White
        people:
          type: array
          description: Characters that belong to this species.
          items:
            type: string
            format: uri
        films:
          type: array
          description: Films in which this species appears.
          items:
            type: string
            format: uri
        url:
          type: string
          format: uri
          description: Canonical URL of the species resource.
    Vehicle:
      type: object
      description: A vehicle that appears in one or more Studio Ghibli films.
      required: [id, name]
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier representing a specific vehicle.
          example: 4e09b023-f650-4747-9ab9-eacf14540cfb
        name:
          type: string
          description: Name of the vehicle.
          example: Air Destroyer Goliath
        description:
          type: string
          description: Short description of the vehicle and its role.
        vehicle_class:
          type: string
          description: Class of the vehicle (e.g. Airship, Aircraft, Submarine).
          example: Airship
        length:
          type: string
          description: Length of the vehicle (string — may include thousands separators).
          example: '1,000'
        pilot:
          type: string
          format: uri
          description: URL reference to the person who pilots the vehicle.
        films:
          type: array
          description: Films in which the vehicle appears.
          items:
            type: string
            format: uri
        url:
          type: string
          format: uri
          description: Canonical URL of the vehicle resource.
    Error:
      type: object
      description: Error response payload.
      properties:
        code:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Human-readable error message.
        fields:
          type: string
          description: Optional list of fields involved in the error.