Welcome to the South Park API! This documentation should help you understand how to utilize the South Park API and become more familiair with it. If you want to know more about this project read the about page. If you have any improvements to the documentation or code, open up a pull request on Github.
Lets make our first request to the South Park API!
To get started making use of the API, use a tool that allows you to make an API request, like curl, Insomnia or the browser. In the below example we're trying to get the first episode with curl:
curl https://spapi.dev/api/episodes/1
Here's the response we get:
That's it! You've done an API call and you can parse the returned data with whatever language you prefer. Your response might look different. Don't worry as there might have been added more code to the API after this is written.
The Base URL is the root URL for all of the API. Always make sure that your API requests start with this URL. If you ever get a 404 not found, check if the Base URL is right first.
The Base URL for the South Park API is:
https://spapi.dev/api/
The documentation below assumes you are prepending the base URL to your API requests.
The API currently does not have any rate limiting. If you are making heavy use of the API, please consider caching the results to limit server load. This might be introduced in the future if there are any signs of abuse.
The South Park API is a completely open API. This means that no authentication is required to make API calls and get data.
All resources support a search parameter that filters the resource returned. This allows you to make queries like:
https://spapi.dev/api/characters?search=eric
All searches will do partial matches with the field(s) that search is enabled on. The individual resource documentation shows which field(s) can be searched for.
All data returned will be a JSON formatted response. This format is not changeable for now.
Represents a character in the South Park Universe.
Endpoints:
/characters - get all the character resources/characters/{id} - get a specific character resourceExample request:
curl https://spapi.dev/api/characters/1
Example response:
Attributes:
id - The id of this charactername - The name this character is known asage - The age of this character in yearssex - The sex of this character (if known). Will be null if it's not known.hair_color - The hair color of this characteroccupation - The occupation of this charactergrade - The grade this character is in (if in school)religion - The main religion of this character (temporary changes of religion not tracked)voiced_by - The voice actor name of this charactercreated_at - The ISO 8601 datetime format of the time that this resource was createdupdated_at - The ISO 8601 datetime format of the time that this resource was updatedurl - The url of this resourcerelatives - An array of relatives with the relative url and relation for this character (from the viewpoint of the queried character)episodes - An array of urls of episodes this character has appeared inSearch fields:
nameAn episode of the South Park series.
Endpoints:
/episodes - get all the episode resources/episodes/{id} - get a specific episode resourceExample request:
curl https://spapi.dev/api/episodes/1
Example response:
Attributes:
id - The id of this episodename - The title of this episodeseason - The season this episode is a part ofepisode - The episode number in the seasonair_date - ISO 8601 date format of the date this episode aireddescription - The description of this episodethumbnail_url - Thumnail URL that references the wiki this API scrapes. These images are quite high resolution, so keep in mind that loading these thumbnails requires quite some bandwidth.wiki_url - URL to the wiki for this episode.created_at - The ISO 8601 datetime format of the time that this resource was createdupdated_at - The ISO 8601 datetime format of the time that this resource was updatedcharacters - An array of characters that made an appearance this episodelocations - An array of locations that made an appearance this episodeSearch fields:
nameA family in the South Park universe.
Endpoints:
/families - get all the family resources/families/{id} - get a specific family resourceExample request:
curl https://spapi.dev/api/families/1
Example response:
Attributes:
id - The id of this familyname - The name of this familycreated_at - The ISO 8601 datetime format of the time that this resource was createdupdated_at - The ISO 8601 datetime format of the time that this resource was updatedcharacters - An array of characters that is a member of this familySearch fields:
nameA location in the South Park universe.
Endpoints:
/locations - get all the location resources/locations/{id} - get a specific location resourceExample request:
curl https://spapi.dev/api/locations/2
Example response:
Attributes:
id - The id of this locationname - The name of this locationcreated_at - The ISO 8601 date format of the time that this resource was createdupdated_at - The ISO 8601 date format of the time that this resource was updatedepisodes - An array of episodes that this location appeared inSearch fields:
name