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:

{
  "data": {
    "id": 1,
    "name": "Cartman Gets an Anal Probe",
    "season": 1,
    "episode": 1,
    "air_date": "1997-08-13",
    "created_at": "2021-07-12T17:50:06+00:00",
    "updated_at": "2021-07-12T17:50:06+00:00",
    "characters": [
      "https://spapi.dev/api/characters/10",
      "https://spapi.dev/api/characters/3",
      "https://spapi.dev/api/characters/27",
      "https://spapi.dev/api/characters/163"
    ],
    "locations": [
      "https://spapi.dev/api/locations/2",
      "https://spapi.dev/api/locations/3",
      "https://spapi.dev/api/locations/6",
      "https://spapi.dev/api/locations/623"
    ]
  }
}

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
  • /characters/schema - get the JSON schema of this resource

Example request:

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

Example response:

{
  "data": {
    "id": 1,
    "name": "Gerald Broflovski",
    "age": null,
    "sex": "Male",
    "hair_color": "Brown",
    "occupation": "Lawyer",
    "grade": null,
    "religion": "Judaism",
    "voiced_by": null,
    "created_at": "2021-07-12T17:48:58+00:00",
    "updated_at": "2021-07-12T17:48:58+00:00",
    "url": "https://spapi.dev/api//characters/1",
    "relatives": [
      {
        "url": "https://spapi.dev/api//characters/2",
        "relation": "Husband"
      },
      {
        "url": "https://spapi.dev/api//characters/3",
        "relation": "Father"
      },
      {
        "url": "https://spapi.dev/api//characters/4",
        "relation": "Adoptive Father"
      },
      {
        "url": "https://spapi.dev/api//characters/6",
        "relation": "Son In-Law"
      },
      {
        "url": "https://spapi.dev/api//characters/7",
        "relation": "Brother"
      },
      {
        "url": "https://spapi.dev/api//characters/8",
        "relation": "Uncle"
      }
    ],
    "episodes": [
      "https://spapi.dev/api//episodes/9",
      "https://spapi.dev/api//episodes/13",
    ]
  }
}

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
  • /episodes/schema - get the JSON schema of this resource

Example request:

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

Example response:

{
  "data": {
    "id": 1,
    "name": "Cartman Gets an Anal Probe",
    "season": 1,
    "episode": 1,
    "air_date": "1997-08-13",
    "created_at": "2021-07-12T17:50:06+00:00",
    "updated_at": "2021-07-12T17:50:06+00:00",
    "characters": [
      "https://spapi.dev/api/characters/10",
      "https://spapi.dev/api/characters/3",
      "https://spapi.dev/api/characters/27",
      "https://spapi.dev/api/characters/163"
    ],
    "locations": [
      "https://spapi.dev/api/locations/2",
      "https://spapi.dev/api/locations/3",
      "https://spapi.dev/api/locations/6",
      "https://spapi.dev/api/locations/623"
    ]
  }
}

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
  • 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

Locations

A location in the South Park universe.

Endpoints:

  • /locations - get all the location resources
  • /locations/{id} - get a specific location resource
  • /locations/schema - get the JSON schema of this resource

Example request:

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

Example response:

{
  "data": {
    "id": 2,
    "name": "Bus Stop",
    "created_at": "2021-07-12T17:48:56+00:00",
    "updated_at": "2021-07-12T17:48:56+00:00",
    "episodes": [
      "https://spapi.dev/api/episodes/1",
      "https://spapi.dev/api/episodes/2"
    ]
  }
}

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