South Park API

South Park API - About

Documentation

General

Introduction

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.

Getting started

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.

Base URL

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.

Rate limiting

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.

Authentication

The South Park API is a completely open API. This means that no authentication is required to make API calls and get data.

Searching

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.

Encoding

All data returned will be a JSON formatted response. This format is not changeable for now.

Resources

Characters

Represents a character in the South Park Universe.

Endpoints:

/characters - get all the character resources
/characters/{id} - get a specific character resource

Example request:

curl https://spapi.dev/api/characters/1

Example response:

Attributes:

id - The id of this character
name - The name this character is known as
age - The age of this character in years
sex - The sex of this character (if known). Will be null if it's not known.
hair_color - The hair color of this character
occupation - The occupation of this character
grade - 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 character
created_at - The ISO 8601 datetime format of the time that this resource was created
updated_at - The ISO 8601 datetime format of the time that this resource was updated
url - The url of this resource
relatives - 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 in

Search fields:

name

Episodes

An episode of the South Park series.

Endpoints:

/episodes - get all the episode resources
/episodes/{id} - get a specific episode resource

Example request:

curl https://spapi.dev/api/episodes/1

Example response:

Attributes:

id - The id of this episode
name - The title of this episode
season - The season this episode is a part of
episode - The episode number in the season
air_date - ISO 8601 date format of the date this episode aired
description - The description of this episode
thumbnail_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 created
updated_at - The ISO 8601 datetime format of the time that this resource was updated
characters - An array of characters that made an appearance this episode
locations - An array of locations that made an appearance this episode

Search fields:

name

Families

A family in the South Park universe.

Endpoints:

/families - get all the family resources
/families/{id} - get a specific family resource

Example request:

curl https://spapi.dev/api/families/1

Example response:

Attributes:

id - The id of this family
name - The name of this family
created_at - The ISO 8601 datetime format of the time that this resource was created
updated_at - The ISO 8601 datetime format of the time that this resource was updated
characters - An array of characters that is a member of this family

Search fields:

name

Locations

A location in the South Park universe.

Endpoints:

/locations - get all the location resources
/locations/{id} - get a specific location resource

Example request:

curl https://spapi.dev/api/locations/2

Example response:

Attributes:

id - The id of this location
name - The name of this location
created_at - The ISO 8601 date format of the time that this resource was created
updated_at - The ISO 8601 date format of the time that this resource was updated
episodes - An array of episodes that this location appeared in

Search fields:

name