Ceci est une ancienne révision du document !
I had wanted to present you with an example of creating your own API wrapper library, but the site that I was going to use has moved to a paid model. However, I have found a different site that does basically the same thing at no cost to you, so I’ll start.
The Movie Database (themoviedb.org) is a great place to find out information about your favorite movies and TV shows, as well as the people who star and help create them. The first thing to do is create an account on the main system and then you can sign up for an API key. Once you have a key, you can query the database through a simple Python program using the wrapper that I’ve created and am presenting here. The API wrapper library covers only a few of the various calls that can be made to the system, mainly the ones that were immediately useful to me and probably to you.
Once you have your key, you should look at the different API calls that can be made and what those calls will return to you. The documentation is at https://developers.themoviedb.org/3/getting-started/introduction, and covers only the version 3 API calls. Most of us will find the Movie information very handy so we’ll look at it first.
Any query for information on a movie or TV show starts with obtaining the ID number of the show you want to investigate. However, in order to obtain the ID, you must first do a search. We must format a URL which includes our API key and the name of the movie. Here is a dummy URL that you can use as an example.
https://api.themoviedb.org/3/search/movie?api_key=«api_key»&language=en-US&query=(MovieName)&page=1&include_adult=false
To break it down, it would be… • Base UR: https://api.themoviedb.org/ • API Version: 3/ • Command: search/ • Type: movie? • API Key: <Your Key Here> & • Language: en-US& • Query: (Movie Name)& • Page #: 1& • Include Adult FIlms: false
There are also two other fields you can use to refine your search, year and primary_release_year.
Let’s say we want to search for the Ant Man movie. Using the above format, the URL would look like this (without the API key):
https://api.themoviedb.org/3/search/movie?api_key=<Your Key Here >&language=en-US&query=Ant%20Man&page=1&include_adult=false®ion=US
The information that comes back will be in JSON format. (Ronnie had a problem with the JSON response, trying to get it to fit nicely in the magazine. So, to see the full response, check the readme at my repository https://github.com/gregwa1953/FCM178 )
Inside the JSON response you will find a field named id as well as fields for original title, overview and so on that will help you decide which of the results contain the ID that you are looking for.
id: 102899, original_language: “en”, original_title: “Ant-Man”, overview: “Armed with the astonishing ability to shrink in scale but increase in strength, master thief Scott Lang must embrace his inner-hero and help his mentor, Doctor Hank Pym, protect the secret behind his spectacular Ant-Man suit from a new generation of towering threats. Against seemingly insurmountable obstacles, Pym and Lang must plan and pull off a heist that will save the world.”,
That gives a fair amount of data about the movie. If that isn’t enough, you can go for the Movie Detail: https://api.themoviedb.org/3/movie/{102899}?api_key=«api_key»&language=en-US
Again, the data comes back in JSON format. (Again, the actual JSON response is shown on my github repository.)
id: 102899, imdb_id: “tt0478970”, original_language: “en”, original_title: “Ant-Man”, overview: “Armed with the astonishing ability to shrink in scale but increase in strength, master thief Scott Lang must embrace his inner-hero and help his mentor, Doctor Hank Pym, protect the secret behind his spectacular Ant-Man suit from a new generation of towering threats. Against seemingly insurmountable obstacles, Pym and Lang must plan and pull off a heist that will save the world.”,
Television series queries would be similar, but in addition to looking for a specific TV series and its details, you can get season and episode details as well. Going even further, for movies you can get the names of the cast and crew, and the same thing for TV shows plus guest stars for each episode (if available).
While you can simply use your API key and run the queries (all of them) via a web browser, I think that it’s a bit simpler to use Python to make the calls. Hence the API wrapper.
So the wrapper is named (imagine how many hours it took me to come up with this name…) wrapper.py. As always, it starts out with a series of imports:
#
# Imports #
import requests import json import pprint import locale
I included pprint to allow me to look at the data in a nice format when I was doing development and for troubleshooting purposes. The locale library helps to make sure that the language field is formatted correctly for the API query for where you are.
Just after the import section, I have the following variable definitions which force them to global variables. In order to use the wrapper library, be sure to assign your API key to the mykey3 variable:
mykey3 = <Your API Key Here>
loc = locale.getlocale()[0]
The first major function will search the movie database by name, and return the requests’ status code, the number of results, the number of pages, and a list of dictionaries that has been snipped out of the JSON data stream.
At this point, you are probably wondering what is the deal with pages? This is very important, since if there are more than about 20 matches found, the API will break the result set into a set of pages. You will need to make multiple requests using the Search Movie query – asking for each page in order. To keep you (and myself) from having to do this, I handle all the requests for the search within the function, and merge all of the data and only a single list of dictionaries.
So the function to search for a movie using the wrapper would be as shown top right.
I have to say, if you have a chance to stream this movie, please do! You won’t be disappointed.
All of the data that is provided in the JSON file is included, it’s just formatted in an easier format for you to deal with, in the endresults variable (again it’s a list of dictionary objects).
Using pretty print, the returns from the function would look like thaat shown next page, top right.
So the information we REALLY want would be the id, so we can simply extract this by using…
movie_id = endresults[0][“id”]
Then the call to get the movie details would be:
status_code, jdata = wrapper.get_movie_by_id(mykey3, movie_id, loc)
And the returned information is shown bottom right.
The current version supports the following functions from the API version 3.
Currently supported functions:
* Search functions will return a number of results depending on query *
Search_movie, search_tvshow, search_multi
* Get detail functions (REQUIRE ID FROM SEARCH FUNCTIONS) *
Get_movie_by_id, get_movie_credits, get_person, get_tvshow_by_id.
Get_tv_season_detail, get_tv_episode_detail, get_tv_show_season_credits,
Get_movie_watch_providers, get_tv_on_air (VERY EXPERIMENTAL)
I’ve decided to go ahead and release this early version (0.4) that you can use as a learning tool.
At the end of the file is a simple test program that you can use by simply calling:
python wrapper.py
If you want to use this in your own programs, just copy it into your project folder and import it into your source code.
As you can see, creating a wrapper for many APIs can be fairly simple. That’s not to say that every API would be this easy, but this should give a good starting point for you to create your own API library wrappers for fun and potentially profit.
I’ve placed the wrapper.py file on my repository at https://github.com/gregwa1953/FCM178
Until next time, as always; stay safe, healthy, positive and creative!