Documentation

Introduction

This documentation will help you get familiar with the resources of the Doctor Who API and show you how to make different queries, so that you can get the most out of it.

REST

Base URL: https://doctorwhoapi.cyclic.app/api

The base URL contains information about all the available API resources. All requests are GET requests and go over HTTPS. All responses return data in JSON.

GET https://doctorwhoapi.cyclic.app/api

{
    'Characters': 'https://doctorwhoapi.cyclic.app/api/characters',
    'Species': 'https://doctorwhoapi.cyclic.app/api/species',
    'Locations': 'https://doctorwhoapi.cyclic.app/api/locations'
}

Currently, these are the available resources:

Character: used to get one or more characters.
Species: used to get one or more species.
Location: used to get one or more locations.

Github

Please feel free to visit the project's Github repository on https://github.com/Ido-Barnea/Doctor-Who-API.

We are happy for any contributions.

Characters

Through the Doctor Who API, you can have access many of the iconic Doctor Who characters!

Character Schema

Key	Type	Description
id	int	The ID of the character.
name	string	The name of the character.
description	string	The description of the character.
status	string	The status of the character ("Alive", "Dead", "Unknown").
species	dictionary<string, string>	A dictionary with the species name and link to the species.
gender	string	The gender of the character ("Male", "Female", "Unknown").
placeOfOrigin	dictionary<string, string>	A dictionary with the location's name and a link to the location.
jobs	string[]	An array of every job the character worked at.
relationsWithTheDoctor	string	The character's relations with the Doctor ("Companion", "Friend", "Foe", "Neutral", "Self").
actors	string[]	An array of every actor/actress who played the character.
image	string	A link to the character's image.

Get All Characters

You can access the list of characters by using the /characters endpoint.

GET https://doctorwhoapi.cyclic.app/api/characters

[
    {
        "id":1,
        "name":"First Doctor",
        "description":"The first incarnation of the Doctor.",
        "status":"Dead",
        "species":"https://doctorwhoapi.cyclic.app/api/species/?name=Time Lord",
        "gender":"Male",
        "placeOfOrigin": {
            "name":"Gallifrey",
            "link":"https://doctorwhoapi.cyclic.app/api/locations/?name=Gallifrey"
        },
        "jobs":["Scrutationary Archivist","Tutor","Sheriff"],
        "relationsWithTheDoctor":"Self",
        "actors":["William Hartnell","Richard Hurndall"],
        "image":"https://upload.wikimedia.org/wikipedia/en/thumb/7/70/First_Doctor_%28Doctor_Who%29.jpg/220px-First_Doctor_%28Doctor_Who%29.jpg"
    }, ...
]

Get A Single Characters

You can get a single character by adding the id as a parameter.

GET https://doctorwhoapi.cyclic.app/api/characters/21

{
    "id":21,
    "name":"Martha Jones",
    "description":"Dr Martha Smith-Jones was a British physician and a companion of the Tenth Doctor.",
    "status":"Alive",
    "species":"https://doctorwhoapi.cyclic.app/api/species/?name=Human",
    "gender":"Female",
    "placeOfOrigin": {
        "name":"Earth",
        "link":"https://doctorwhoapi.cyclic.app/api/locations/?name=Earth"
    },
    "jobs":["Physician"],
    "relationsWithTheDoctor":"Companion",
    "actors":["Freema Agyeman"],
    "image":"https://static.wikia.nocookie.net/tardis/images/d/d9/MarthaAfter42.jpg/revision/latest/scale-to-width-down/350?cb=20191010171632"
}

Filter Characters

You can also include filters in the URL by including additional query parameters. To start filtering add a ? followed by the query <query>=<value>. If you want to chain several queries in the same call, use & followed by the query. For example, if you want to get all the characters who are Alive and Female, just add
?status=Alive&gender=Female to the URL.

Available Parameters:

name filter by name.
status filter by status ("Alive", "Dead", "Unknown").
species filter by species.
gender filter by gender.
placeOfOrigin filter by place of origin.
relationsWithTheDoctor filter by relations with the Doctor ("Companion", "Friend", "Foe", "Neutral", "Self").

GET https://doctorwhoapi.cyclic.app/api/characters/?status=Alive&gender=Female

[
    {
        "id":17,
        "name":"Rose Tyler",
        "description":"Rose Marion Tyler, knighted Dame Rose of the Powell Estate, was a companion of the Ninth and Tenth Doctors.",
        "status":"Alive",
        "species":"https://doctorwhoapi.cyclic.app/api/species/?name=Human",
        "gender":"Female",
        "placeOfOrigin": {
            "name":"Earth",
            "link":"https://doctorwhoapi.cyclic.app/api/locations/?name=Earth"
        },
        "jobs":["Shop assistant","Dinner lady","Teacher"],
        "relationsWithTheDoctor":"Companion",
        "actors":["Billie Piper"],
        "image":"https://upload.wikimedia.org/wikipedia/en/thumb/7/74/Rose_Tyler.jpg/220px-Rose_Tyler.jpg"
    }, ...
]

Species

You can also access many of the unique species the Doctor Who universe has to offer!

Species Schema

Key	Type	Description
id	int	The ID of the species.
name	string	The name of the species.
description	string	The description of the species.
placeOfOrigin	dictionary<string, string>	A dictionary with the species name and a link to the species.
image	string	A link to the species's image.

Get All Species

You can access the list of species by using the /species endpoint.

GET https://doctorwhoapi.cyclic.app/api/species

[
    {
        "id":1,
        "name":"Dalek",
        "description":"The Daleks were a warrior race made up of genetically engineered mutants belonging to fundamental DNA type 467-989. On many occasions, the Daleks openly acknowledged a single Time Lord, the Doctor, as their greatest enemy.",
        "planetOfOrigin": {
            "name":"Skaro",
            "link":"https://doctorwhoapi.cyclic.app/api/locations/?name=Skaro"
        },
        "image":"https://static.wikia.nocookie.net/tardis/images/8/8d/Zeg_and_the_Emperor.jpg/revision/latest/scale-to-width-down/350?cb=20210327012145"
    }, ...
]

Get A Single Species

You can get a single species by adding the id as a parameter.

GET https://doctorwhoapi.cyclic.app/api/species/9

{
    "id":9,
    "name":"Silurian",
    "description":"The Silurians, also known as Earth Reptiles, Eocenes, reptile people, Psionosauropodomorpha, Homo Reptilicus, Homo reptilia and Reptilia sapiens, were a species native to Earth that pre-dated humanity.",
    "placeOfOrigin": {
        "name":"Earth",
        "link":"https://doctorwhoapi.cyclic.app/api/locations/?name=Earth"
    },
    "image":"https://static.wikia.nocookie.net/tardis/images/b/b5/Wenley_and_Wales.jpg/revision/latest/scale-to-width-down/350?cb=20110703184954"
}

Filter Species

Available Parameters:

name filter by name.
placeOfOrigin filter by place of origin.

If you want to learn how to use queries, look here

Locations

You can also access many of the interesting locations the exist in the Doctor Who universe!

Locations Schema

Key	Type	Description
id	int	The ID of the species.
name	string	The name of the species.
type	string	The type of location (e.g. Planet / Structure / etc.).
description	string	The description of the location.
image	string	A link to the location's image.

Get All Locations

You can access the list of locations by using the /locations endpoint.

GET https://doctorwhoapi.cyclic.app/api/locations

 [
    {
        "id":1,
        "name":"Gallifrey",
        "type":"Planet",
        "description":"Gallifrey was the homeworld of the Time Lords. By one account, the planet was actually named Jewel. The literal translation of the name \"Gallifrey\" was \"They that walk in the shadows\", and indeed, \"the Shadow People\" was one of the names given to the planet's inhabitants.",
        "image":"https://static.wikia.nocookie.net/tardis/images/d/d5/GallifreyReturns-1-.jpg/revision/latest/scale-to-width-down/350?cb=20120410032325"
    }, ...
]

Get A Single Location

You can get a single location by adding the id as a parameter.

GET https://doctorwhoapi.cyclic.app/api/locations/10

{
    "id":10,
    "name":"Last Chance Saloon",
    "type":"Building",
    "description":"The Last Chance Saloon was a bar in Tombstone, Arizona. It was owned by Charlie, who employed Kate Fisher as a singer.",
    "image":"https://static.wikia.nocookie.net/tardis/images/0/09/Steven%2C_Dodo_and_Phineas.jpg/revision/latest/scale-to-width-down/350?cb=20140905104701"
}

Filter Locations

Available Parameters:

name filter by name.
type filter by type.

If you want to learn how to use queries, look here