Complete Studio Ghibli API Guide 2025: Ultimate Development Tutorial with Examples
Master the Studio Ghibli API with this comprehensive guide featuring detailed endpoints, code samples in multiple languages, and real-world application examples. Perfect for creating anime-inspired applications with the beloved Ghibli universe!
Complete Studio Ghibli API Guide 2025: Ultimate Development Tutorial with Examples

The Studio Ghibli API provides developers with a treasure trove of data from the magical world of Studio Ghibli films. This unofficial API catalogs the characters, locations, vehicles, species, and of course, the beloved films that have captivated audiences worldwide. Whether you're building a fan site, creating a mobile app, or just exploring API integration, this comprehensive guide will help you harness the full potential of the Studio Ghibli API.
🔥 April 2025 Update: This guide covers the latest version of the Studio Ghibli API, including new endpoints and improved documentation. All code samples have been verified to work with the current API implementation.

Introduction to the Studio Ghibli API
The Studio Ghibli API is a RESTful web service that provides information about the Studio Ghibli universe. Created as a fan project, it allows developers to access structured data about the films, characters, locations, and more, all available for free.
API Features:
- Comprehensive Data: Access information on films, people, locations, species, and vehicles
- JSON Format: All data is returned in easy-to-parse JSON format
- No Authentication: Simple to use with no API keys required
- HTTPS Support: Secure connections for all API calls
- Cross-Origin Support: Enabled CORS for front-end applications
Base URL
The base URL for all API requests is:
https://ghibliapi.vercel.app
Note that the API was previously hosted at https://ghibliapi.herokuapp.com
, but as of December 2022, the original repository was archived. The community has maintained mirrors, with Vercel hosting being the most reliable option as of 2025.
API Endpoints and Resources
The Studio Ghibli API offers several endpoints to access different types of data. Let's explore each one:
1. Films Endpoint
The films endpoint provides information about all Studio Ghibli movies.
Endpoint: /films
Example Request:
hljs bashcurl https://ghibliapi.vercel.app/films
Single Film Request:
hljs bashcurl https://ghibliapi.vercel.app/films/58611129-2dbc-4a81-a72f-77ddfc1b1b49
Response Structure:
hljs json{
"id": "58611129-2dbc-4a81-a72f-77ddfc1b1b49",
"title": "My Neighbor Totoro",
"original_title": "となりのトトロ",
"original_title_romanised": "Tonari no Totoro",
"description": "Two sisters move to the country with their father in order to be closer to their hospitalized mother, and discover the surrounding trees are inhabited by Totoros, magical spirits of the forest. When the youngest runs away from home, the older sister seeks help from the spirits to find her.",
"director": "Hayao Miyazaki",
"producer": "Hayao Miyazaki",
"release_date": "1988",
"running_time": "86",
"rt_score": "93",
"people": ["https://ghibliapi.vercel.app/people/..."],
"species": ["https://ghibliapi.vercel.app/species/..."],
"locations": ["https://ghibliapi.vercel.app/locations/..."],
"vehicles": ["https://ghibliapi.vercel.app/vehicles/..."],
"url": "https://ghibliapi.vercel.app/films/58611129-2dbc-4a81-a72f-77ddfc1b1b49"
}
2. People Endpoint
This endpoint provides information about characters from Studio Ghibli films.
Endpoint: /people
Example Request:
hljs bashcurl https://ghibliapi.vercel.app/people
Single Character Request:
hljs bashcurl https://ghibliapi.vercel.app/people/40c005ce-3725-4f15-8409-3e1b1b14b583
Response Structure:
hljs json{
"id": "40c005ce-3725-4f15-8409-3e1b1b14b583",
"name": "Ashitaka",
"gender": "Male",
"age": "late teens",
"eye_color": "Brown",
"hair_color": "Brown",
"films": ["https://ghibliapi.vercel.app/films/0440483e-ca0e-4120-8c50-4c8cd9b965d6"],
"species": "https://ghibliapi.vercel.app/species/af3910a6-429f-4c74-9ad5-dfe1c4aa04f2",
"url": "https://ghibliapi.vercel.app/people/40c005ce-3725-4f15-8409-3e1b1b14b583"
}
3. Locations Endpoint
This endpoint provides information about locations featured in Studio Ghibli films.
Endpoint: /locations
Example Request:
hljs bashcurl https://ghibliapi.vercel.app/locations
Single Location Request:
hljs bashcurl https://ghibliapi.vercel.app/locations/11014596-71b0-4b3e-b8c0-1c4b15f28b9a
Response Structure:
hljs json{
"id": "11014596-71b0-4b3e-b8c0-1c4b15f28b9a",
"name": "Irontown",
"climate": "Continental",
"terrain": "Mountain",
"surface_water": "40",
"residents": ["https://ghibliapi.vercel.app/people/..."],
"films": ["https://ghibliapi.vercel.app/films/0440483e-ca0e-4120-8c50-4c8cd9b965d6"],
"url": "https://ghibliapi.vercel.app/locations/11014596-71b0-4b3e-b8c0-1c4b15f28b9a"
}
4. Species Endpoint
This endpoint provides information about the various species featured in Studio Ghibli films.
Endpoint: /species
Example Request:
hljs bashcurl https://ghibliapi.vercel.app/species
Single Species Request:
hljs bashcurl https://ghibliapi.vercel.app/species/af3910a6-429f-4c74-9ad5-dfe1c4aa04f2
Response Structure:
hljs json{
"id": "af3910a6-429f-4c74-9ad5-dfe1c4aa04f2",
"name": "Human",
"classification": "Mammal",
"eye_colors": "Black, Blue, Brown, Grey, Green, Hazel",
"hair_colors": "Black, Blonde, Brown, Grey, White",
"people": ["https://ghibliapi.vercel.app/people/..."],
"films": ["https://ghibliapi.vercel.app/films/..."],
"url": "https://ghibliapi.vercel.app/species/af3910a6-429f-4c74-9ad5-dfe1c4aa04f2"
}
5. Vehicles Endpoint
This endpoint provides information about vehicles featured in Studio Ghibli films.
Endpoint: /vehicles
Example Request:
hljs bashcurl https://ghibliapi.vercel.app/vehicles
Single Vehicle Request:
hljs bashcurl https://ghibliapi.vercel.app/vehicles/4e09b023-f650-4747-9ab9-eacf14540cfb
Response Structure:
hljs json{
"id": "4e09b023-f650-4747-9ab9-eacf14540cfb",
"name": "Air Destroyer Goliath",
"description": "A military airship utilized by the government to access Laputa",
"vehicle_class": "Airship",
"length": "1,000",
"pilot": "https://ghibliapi.vercel.app/people/40c005ce-3725-4f15-8409-3e1b1b14b583",
"films": ["https://ghibliapi.vercel.app/films/2baf70d1-42bb-4437-b551-e5fed5a87abe"],
"url": "https://ghibliapi.vercel.app/vehicles/4e09b023-f650-4747-9ab9-eacf14540cfb"
}
Integration Examples in Multiple Languages
Let's explore how to integrate the Studio Ghibli API in different programming languages.
JavaScript (Fetch API)
hljs javascript// Fetch all Ghibli films
async function getGhibliFilms() {
try {
const response = await fetch('https://ghibliapi.vercel.app/films');
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const films = await response.json();
// Process the films data
console.log(`Found ${films.length} films:`);
films.forEach(film => {
console.log(`- ${film.title} (${film.release_date}): ${film.description.substring(0, 100)}...`);
});
return films;
} catch (error) {
console.error('Error fetching Ghibli films:', error);
}
}
// Fetch details for a specific film
async function getFilmDetails(filmId) {
try {
const response = await fetch(`https://ghibliapi.vercel.app/films/${filmId}`);
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('Error fetching film details:', error);
}
}
// Example usage
getGhibliFilms().then(films => {
if (films && films.length > 0) {
// Get details for "My Neighbor Totoro"
return getFilmDetails('58611129-2dbc-4a81-a72f-77ddfc1b1b49');
}
}).then(filmDetails => {
if (filmDetails) {
console.log('Film details:', filmDetails);
}
});
Python (Requests Library)
hljs pythonimport requests
def get_ghibli_films():
"""Fetch all Studio Ghibli films"""
try:
response = requests.get('https://ghibliapi.vercel.app/films')
response.raise_for_status() # Raise exception for HTTP errors
films = response.json()
print(f"Found {len(films)} films:")
for film in films:
print(f"- {film['title']} ({film['release_date']}): {film['description'][:100]}...")
return films
except requests.exceptions.RequestException as e:
print(f"Error fetching Ghibli films: {e}")
return None
def get_film_details(film_id):
"""Fetch details for a specific film"""
try:
response = requests.get(f'https://ghibliapi.vercel.app/films/{film_id}')
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"Error fetching film details: {e}")
return None
def get_film_with_characters(film_id):
"""Fetch a film and its characters"""
film = get_film_details(film_id)
if not film:
return None
# Get characters from the film
characters = []
for people_url in film.get('people', []):
if people_url != "https://ghibliapi.vercel.app/people/":
try:
response = requests.get(people_url)
response.raise_for_status()
characters.append(response.json())
except requests.exceptions.RequestException:
continue
return {
'film': film,
'characters': characters
}
# Example usage
if __name__ == "__main__":
films = get_ghibli_films()
if films:
# Get details for "Princess Mononoke" with characters
film_with_chars = get_film_with_characters('0440483e-ca0e-4120-8c50-4c8cd9b965d6')
if film_with_chars:
print(f"\nDetailed info for: {film_with_chars['film']['title']}")
print(f"Number of characters: {len(film_with_chars['characters'])}")
for char in film_with_chars['characters']:
print(f"- {char['name']} ({char['gender']})")
React Component Example
Here's a simple React component that displays a list of Studio Ghibli films:
hljs jsximport React, { useState, useEffect } from 'react';
import './GhibliFilmList.css';
const GhibliFilmList = () => {
const [films, setFilms] = useState([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
const [selectedFilm, setSelectedFilm] = useState(null);
useEffect(() => {
const fetchFilms = async () => {
try {
const response = await fetch('https://ghibliapi.vercel.app/films');
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const data = await response.json();
setFilms(data);
setLoading(false);
} catch (err) {
setError(err.message);
setLoading(false);
}
};
fetchFilms();
}, []);
const handleFilmSelect = async (id) => {
if (selectedFilm && selectedFilm.id === id) {
setSelectedFilm(null);
return;
}
try {
const response = await fetch(`https://ghibliapi.vercel.app/films/${id}`);
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const data = await response.json();
setSelectedFilm(data);
} catch (err) {
setError(err.message);
}
};
if (loading) return <div className="loading">Loading Studio Ghibli films...</div>;
if (error) return <div className="error">Error: {error}</div>;
return (
<div className="ghibli-container">
<h1>Studio Ghibli Films</h1>
<div className="film-list">
{films.map(film => (
<div
key={film.id}
className={`film-card ${selectedFilm && selectedFilm.id === film.id ? 'selected' : ''}`}
onClick={() => handleFilmSelect(film.id)}
>
<h2>{film.title}</h2>
<div className="film-info">
<p><strong>Director:</strong> {film.director}</p>
<p><strong>Released:</strong> {film.release_date}</p>
<p><strong>RT Score:</strong> {film.rt_score}%</p>
</div>
</div>
))}
</div>
{selectedFilm && (
<div className="film-details">
<h2>{selectedFilm.title} ({selectedFilm.original_title})</h2>
<p className="romanised">{selectedFilm.original_title_romanised}</p>
<div className="film-metadata">
<p><strong>Director:</strong> {selectedFilm.director}</p>
<p><strong>Producer:</strong> {selectedFilm.producer}</p>
<p><strong>Release Date:</strong> {selectedFilm.release_date}</p>
<p><strong>Running Time:</strong> {selectedFilm.running_time} minutes</p>
<p><strong>RT Score:</strong> {selectedFilm.rt_score}%</p>
</div>
<p className="description">{selectedFilm.description}</p>
</div>
)}
</div>
);
};
export default GhibliFilmList;
Advanced Usage Examples
1. Relationship Mapping
One of the powerful aspects of the Studio Ghibli API is the interconnected nature of its resources. Let's create a utility function to traverse these relationships:
hljs javascript// Utility to resolve API references and build a complete object
async function resolveReferences(baseObject, relationshipsToResolve) {
const result = { ...baseObject };
for (const relation of relationshipsToResolve) {
if (!baseObject[relation] ||
(Array.isArray(baseObject[relation]) && baseObject[relation].length === 0)) {
continue;
}
if (Array.isArray(baseObject[relation])) {
result[relation] = [];
for (const url of baseObject[relation]) {
if (url.includes('https://ghibliapi.vercel.app/')) {
try {
const response = await fetch(url);
if (response.ok) {
const data = await response.json();
result[relation].push(data);
}
} catch (error) {
console.warn(`Failed to resolve: ${url}`, error);
}
}
}
} else if (typeof baseObject[relation] === 'string' &&
baseObject[relation].includes('https://ghibliapi.vercel.app/')) {
try {
const response = await fetch(baseObject[relation]);
if (response.ok) {
result[relation] = await response.json();
}
} catch (error) {
console.warn(`Failed to resolve: ${baseObject[relation]}`, error);
}
}
}
return result;
}
// Example: Get a film with all related entities resolved
async function getCompleteFilmData(filmId) {
try {
const filmResponse = await fetch(`https://ghibliapi.vercel.app/films/${filmId}`);
if (!filmResponse.ok) {
throw new Error(`HTTP error! Status: ${filmResponse.status}`);
}
const film = await filmResponse.json();
const completeFilm = await resolveReferences(film, ['people', 'locations', 'vehicles', 'species']);
console.log('Complete film data:', completeFilm);
return completeFilm;
} catch (error) {
console.error('Error fetching complete film data:', error);
}
}
// Usage
getCompleteFilmData('58611129-2dbc-4a81-a72f-77ddfc1b1b49'); // My Neighbor Totoro
2. Search Functionality
The API doesn't provide built-in search functionality, but we can implement our own:
hljs javascript// Function to search across all Ghibli resources
async function searchGhibliData(query) {
query = query.toLowerCase();
const results = {
films: [],
people: [],
locations: [],
species: [],
vehicles: []
};
// Helper function to fetch and filter a resource type
async function fetchAndFilter(resourceType, searchFields) {
try {
const response = await fetch(`https://ghibliapi.vercel.app/${resourceType}`);
if (!response.ok) {
console.warn(`Couldn't fetch ${resourceType}`);
return;
}
const items = await response.json();
results[resourceType] = items.filter(item => {
return searchFields.some(field => {
const value = item[field];
return value && value.toLowerCase().includes(query);
});
});
} catch (error) {
console.error(`Error searching ${resourceType}:`, error);
}
}
// Search in parallel across all resource types
await Promise.all([
fetchAndFilter('films', ['title', 'original_title', 'description', 'director', 'producer']),
fetchAndFilter('people', ['name', 'gender', 'age', 'eye_color', 'hair_color']),
fetchAndFilter('locations', ['name', 'climate', 'terrain']),
fetchAndFilter('species', ['name', 'classification']),
fetchAndFilter('vehicles', ['name', 'description', 'vehicle_class'])
]);
// Compute total results
const totalResults = Object.values(results).reduce((sum, items) => sum + items.length, 0);
console.log(`Found ${totalResults} results for "${query}"`);
return results;
}
// Usage
searchGhibliData('totoro').then(results => {
console.log('Search results:', results);
});
3. Building a Local Cache
For applications that need to minimize API calls, building a local cache is useful:
hljs javascriptclass GhibliApiCache {
constructor(cacheDuration = 3600000) { // Default: 1 hour
this.cache = {
films: { data: null, timestamp: 0 },
people: { data: null, timestamp: 0 },
locations: { data: null, timestamp: 0 },
species: { data: null, timestamp: 0 },
vehicles: { data: null, timestamp: 0 }
};
this.cacheDuration = cacheDuration;
this.baseUrl = 'https://ghibliapi.vercel.app';
}
async get(resourceType, id = null) {
// Check if we need to refresh the cache
const now = Date.now();
const cacheEntry = this.cache[resourceType];
if (!cacheEntry.data || (now - cacheEntry.timestamp > this.cacheDuration)) {
try {
const response = await fetch(`${this.baseUrl}/${resourceType}`);
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
cacheEntry.data = await response.json();
cacheEntry.timestamp = now;
} catch (error) {
console.error(`Error refreshing cache for ${resourceType}:`, error);
return id ? null : [];
}
}
// Return either a specific item or the whole collection
if (id) {
return cacheEntry.data.find(item => item.id === id) || null;
}
return cacheEntry.data;
}
// Clear the entire cache or a specific resource type
clearCache(resourceType = null) {
if (resourceType) {
if (this.cache[resourceType]) {
this.cache[resourceType] = { data: null, timestamp: 0 };
}
} else {
Object.keys(this.cache).forEach(key => {
this.cache[key] = { data: null, timestamp: 0 };
});
}
}
}
// Usage example
const ghibliCache = new GhibliApiCache();
async function displayCachedFilms() {
const films = await ghibliCache.get('films');
console.log(`Loaded ${films.length} films from cache`);
// Get a specific film (will use cache)
const totoro = await ghibliCache.get('films', '58611129-2dbc-4a81-a72f-77ddfc1b1b49');
console.log('Film details from cache:', totoro);
}
displayCachedFilms();
Real-World Application Examples
Let's explore some practical applications you can build using the Studio Ghibli API:
1. Ghibli Film Explorer
Create a comprehensive web app that allows users to explore the Ghibli universe with detailed information about films, characters, and locations. Features could include:
- Film browsing with filters for director, release year, and rating
- Character profiles with related films
- Interactive map of Ghibli locations
- Timeline of the Ghibli universe
2. Ghibli Trivia Game
Build a fun trivia game testing users' knowledge of Studio Ghibli films:
- Pull questions dynamically from the API data
- Multiple difficulty levels
- Score tracking and leaderboards
- Timed challenges
3. Ghibli Recommendation Engine
Create a recommendation system that suggests Ghibli films based on user preferences:
- Ask users about their favorite genres, themes, or existing Ghibli films
- Match preferences with film descriptions and metadata
- Provide personalized film recommendations with justifications
- Allow users to rate recommendations to improve future suggestions
Best Practices and Optimizations
When working with the Studio Ghibli API, follow these best practices for optimal performance:
1. Implement Caching
The API data doesn't change frequently, so implementing client-side caching can significantly improve your application's performance and reduce API calls:
- Use localStorage for web applications
- Implement disk caching for mobile apps
- Set reasonable cache expiration times (24 hours is generally sufficient)
2. Handle API Limitations
While the Studio Ghibli API is free and has no strict rate limits, it's good practice to be respectful of the service:
- Implement exponential backoff for retries
- Batch requests when possible
- Pre-fetch and cache data during low-usage periods
3. Error Handling
Robust error handling ensures your application remains functional even when API issues occur:
- Always wrap API calls in try/catch blocks
- Provide meaningful error messages to users
- Implement graceful fallbacks when data can't be fetched
- Include offline support with cached data
4. Performance Optimization
For larger applications, consider these performance optimization strategies:
- Use pagination when displaying large result sets
- Implement lazy loading for images and detailed content
- Minimize the payload by requesting only needed fields (though the API doesn't currently support field filtering)
- Use web workers for data processing in browser applications
API Alternatives and Supplements
If you need additional functionality or want to enhance your Ghibli-themed application, laozhang.ai API Service offers the best solution for integrating AI capabilities with your Ghibli projects.
1. laozhang.ai API Service - Recommended Solution
The laozhang.ai API service provides the most cost-effective access to powerful AI models like GPT-4o and Claude 3.5 at a fraction of the official price:
- Significant Cost Savings: Access top-tier AI models at up to 75% discount compared to official pricing
- Identical API Interface: Compatible with OpenAI and Anthropic API specifications
- Enhanced Stability: Reliable connections even during peak usage times
- Free Credits on Registration: Start developing immediately with complimentary credits
- No Complex Setup: Simple integration with any application
- Specialized for Creative Content: Perfect for generating Ghibli-style descriptions, stories, and character analyses
2. Community-Maintained Ghibli API Forks
Since the original repository is now archived, community forks provide ongoing maintenance:
- Check GitHub for active forks with recent updates
- Consider hosting your own instance if you need specific customizations
Using laozhang.ai API Service for Ghibli-Style AI Generation
Enhance your Ghibli application with AI-powered features using laozhang.ai's API service, which provides the most affordable access to powerful models like GPT-4o and Claude 3.5.
Example: Generating Ghibli-Style Descriptions with GPT-4o
hljs javascriptasync function generateGhibliDescription(character, setting) {
const apiKey = 'your_laozhang_api_key';
const url = 'https://api.laozhang.ai/v1/chat/completions';
try {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`
},
body: JSON.stringify({
model: 'gpt-4o-all',
stream: false,
messages: [
{
role: 'system',
content: 'You are a creative writer who specializes in Studio Ghibli-style storytelling. Create magical, whimsical descriptions in the style of Hayao Miyazaki.'
},
{
role: 'user',
content: `Write a short, Ghibli-style description for a character named ${character} who lives in ${setting}.`
}
]
})
});
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const data = await response.json();
return data.choices[0].message.content;
} catch (error) {
console.error('Error generating Ghibli description:', error);
return null;
}
}
// Usage example
generateGhibliDescription('Mika', 'a floating island with giant windmills')
.then(description => {
console.log('Generated Ghibli description:');
console.log(description);
});
Additional AI Integration Examples with laozhang.ai
Here are some other creative ways to enhance your Ghibli application using laozhang.ai:
- Character Dialogue Generation: Create interactive conversations with Ghibli-inspired characters
- Plot Summarization: Generate concise summaries of complex Ghibli film plots
- Location Descriptions: Craft detailed descriptions of Ghibli-style magical locations
- Fan Fiction Support: Help users create their own stories set in the Ghibli universe
- Translation Services: Translate content between languages while maintaining the Ghibli aesthetic
To register for laozhang.ai API service and receive free credits to start developing, visit: https://api.laozhang.ai/register/?aff_code=JnIT
Conclusion
The Studio Ghibli API offers a fantastic opportunity for developers to integrate the magical world of Ghibli into their applications. With the comprehensive examples and best practices provided in this guide, you're now equipped to build rich, engaging applications that celebrate these beloved animated classics.
Whether you're creating a fan site, a mobile application, or just exploring API integration, the Studio Ghibli API provides a wealth of data to bring your projects to life. Happy coding, and may your applications be as enchanting as the Ghibli universe itself!
FAQ
Can I use the Studio Ghibli API commercially?
The API is primarily intended for non-commercial and educational use. For commercial applications, it's best to contact the original creators or check the current terms of service on the hosting platform.
Does the API require authentication?
No, the Studio Ghibli API is open and does not require API keys or authentication.
How often is the API data updated?
The API data is relatively static since it's based on existing films. Major updates typically only occur if new films are released or if there are corrections to existing data.
Is there a rate limit for API requests?
There's no official rate limit documented, but as with any public API, it's good practice to implement reasonable limits in your application to avoid overloading the service.
Can I contribute to the API or report issues?
Since the original repository is archived, contributions would need to be made to community-maintained forks. Check GitHub for active forks where you can report issues or submit pull requests.
Updates and Changes
hljs plaintext┌─ Update Log ────────────────────────┐ │ 2025-04-18: Initial comprehensive │ │ guide published │ │ 2025-04-10: API endpoints verified │ │ 2025-04-05: Code examples tested │ └─────────────────────────────────────┘
🌟 This guide will be regularly updated to reflect any changes to the Studio Ghibli API or to add new integration examples and best practices.