Homework 6: Search Server-side Scripting using Python Flask, JSON, and Ticketmaster API
1. Objectives
● Get experience with the Python programming language and Flask framework
● Get experience with the Google API and Ticketmaster API
● Get experience creating web pages using HTML, CSS, JavaScript, DOM, JSON format
and XMLHttpRequest object
● Get experience using JSON parsers in Python and JavaScript
● Getting hands-on experience in Google Cloud App Engine.
1.1. Cloud exercise
The back end of this homework must be implemented in the cloud on Google Cloud App Engine, using Python.
● See assignment #5 for installation of needed components on Google Cloud.
● See the hints in section 3; a lot of reference material is provided to you.
● For Python and Flask kick-start, please refer to the Lecture slides on the class website.
● You must refer to the grading guidelines, the video, the specs, and Piazza. Styling will be
graded, and the point’s breakup is mentioned in the grading guidelines.
2. Description
In this exercise, you are asked to create a webpage that allows you to search for events information using the Ticketmaster API, and the results will be displayed in a tabular format. The page will also provide event details.
2.1. Description of the Search Form
The user first opens a web page (for example, event.html, or any valid web page name). You should use the ipinfo.io API (See hint 3.3) to fetch the user’s geolocation, after which the search button should be enabled (it is initially greyed out and disabled when the page loads).
The user must enter a keyword and choose what Category of the event he/she wants to search (categories include Music, Sports, Arts & Theatre, Film, Miscellaneous) from a drop-down list. The default value for the “Category” drop-down list is “Default”, which covers all the “types” provided by the Ticketmaster API.
Also, the user can choose the distance (in miles), which is the radius for the search where the center is “Here” (the current location returned from ipinfo.io API) or the location listed in the edit box. When the “Here” radio button is selected, the location edit box must be disabled. When the location edit box is selected, it is a required field, and a location string must be entered. The default distance is 10 miles from the chosen location. Use HTML5 “placeholder” to show the
string “location” in the location edit box and “10” in the Distance edit box as the initial values. An example is shown in Figure 1.
Figure 1(a): Initial Search Screen (Search button disabled)
Figure 1(b): Search Screen (after fetched location) The search form has two buttons:
• Search button: The button must be disabled while the page is fetching the user’s geolocation and must be enabled once the geolocation is obtained. An example of valid input is shown in Figure 2. Once the user has provided valid input, your client script should send a request to your web server script with the form inputs. You must use GET to transfer the form data to your web server (do not use POST, as you would be unable to provide a sample link to your cloud services). A Python script using Flask will retrieve the form inputs and send it to the Ticketmaster API event search service. You need to use the Flask Python framework to make all the API calls.
If the user clicks on the search button without providing a value in the “Keyword” field or “location” edit box, you should show an error “tooltip” that indicates which field is missing. Examples are shown in Figure 3a and 3b.
Using XMLHttpRequest or any other JavaScript calls for anything other than calling your own “cloud” backend will lead to a 4-point penalty. Do not call the Ticketmaster API directly from JavaScript.
2
•
Define routing endpoints and make your API call from the Python backend. The recommended tutorial for Flask and more importantly, routing, can be found at the following link: https://flask.palletsprojects.com/en/1.1.x/
Clear button: This button must clear the result area (below the search area) and set all fields to the default values in the search area. The clear operation must be done using a JavaScript function.
Figure 2: An Example of a valid Search
Figure 3(a): An Example of Invalid Search (empty input)
Figure 3(b): An Example of Invalid Search (empty location)
3
2.2 Displaying Events Results Table
In this section, we outline how to use the form inputs to construct the calls to the RESTful web services to the Ticketmaster API service and display the result in the web page.
The Ticketmaster API is documented here:
https://developer.ticketmaster.com
If the location edit box is selected, your client JavaScript uses the input address to get the geocoding via Google Maps Geocoding API. The Google Maps Geocoding API is documented here:
https://developers.google.com/maps/documentation/geocoding/start
The Google Maps Geocoding API expects two parameters:
• address: The street address that you want to geocode, in the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided.
• key: Your application’s API key. This key identifies your application for purposes of quota management. (Explained in Section 3.1).
2.2.1 Geocoding
An example of an HTTP request to the Google Maps Geocoding API, when the location address is “University of Southern California, CA” is shown below:
The response includes the latitude and longitude of the address. Figure 4 shows an example of the JSON object returned in the Google Maps Geocoding API web service response.
https://maps.googleapis.com/maps/api/geocode/json?address=University+of+So uthern+California+CA&key=YOUR_API_KEY
4
Figure 4: A sample result of Google Maps Geocoding query
The latitude and longitude of the address are needed when constructing a restful web service URL to retrieve all entities matching the user query. The Ticketmaster API “Event Search” service uses geohash to represent the address location, instead of latitude and longitude. You can convert latitude/longitude to geohash on the client or server side.
A Python library for geohash encoding is available online. The source code can be found here:
https://pypi.org/project/geolib/
Call the function geihash.encode() as in:
geohash = geohash.encode(‘70.2995’, ‘-27.9993’, 7)
A JavaScript library for the same lat/long -> geohash conversion is available here:
https://www.movable-type.co.uk/scripts/geohash.html
and here:
https://github.com/chrisveness/latlon-geohash/blob/master/latlon-geohash.js
Call the function Geohash.encode() as in:
5
const geohash = Geohash.encode(52.205, 0.119, 7);
2.2.2. Ticketmaster API Event Search service
The Ticketmaster API Event Search service is documented here: https://developer.ticketmaster.com/products-and-docs/apis/discovery-api/v2/#search-events-v2 The Ticketmaster API Event Search service expects the following parameters:
• apikey: Your application’s API key. This key identifies your application for purposes of quota management.
• geoPoint: The geohash around which to retrieve event information. The geohash is calculated by latitude and longitude values.
• radius: The distance within which to return event results.
• segmentId: Filters the results to events matching the specified type id. Only one category
may be specified (see Table 1). Leave the field empty means searching in all categories. Table 1: Ticketmaster API – SegmentId Values for Various Event Categories
Category
SegmentId
Music
KZFzniwnSyZfZ7v7nJ
Sports
KZFzniwnSyZfZ7v7nE
Arts & Theatre
KZFzniwnSyZfZ7v7na
Film
KZFzniwnSyZfZ7v7nn
Miscellaneous
KZFzniwnSyZfZ7v7n1
• unit: Unit of the radius. There are two options, “miles” and “km”. Use “miles”.
• keyword: A term to be matched against all content that Google has indexed for this place,
including but not limited to name, type, and address, as well as customer reviews and other third-party content.
An example of an HTTP request to the Ticketmaster API Event Search that searches for the nearby sport events near the University of Southern California within a 10 miles radius is shown below:
Figure 5 shows an example of the JSON response returned by the Ticketmaster API Event Search service response.
https://app.ticketmaster.com/discovery/v2/events.json?apikey= YOUR_API_KEY &keyword=University+of+Southern+California&segmentId=KZFzniwnSyZfZ7v7nE &radius=10&unit=miles&geoPoint=9q5cs
6
Figure 5: A sample JSON response returned by the Ticketmaster API Event Search
The Python script should pass the returned JSON object to the client side or parse the returned JSON and extract useful fields and pass these fields to the client side in a JSON-formatted object. You should use JavaScript to parse the JSON object, extract the needed fields, and display the results in a tabular format. A sample output is shown in Figure 6. The displayed table includes five columns: Date, Icon, Event Name, Genre, and Venue Name. If the API service returns an empty result set, the page should display “No records have been found” as shown in Figure 7.
Figure 6: An Example of a Valid Search result
7
Figure 7: An Example of an Empty Search result
When the search result contains at least one record, you need to map the data extracted from the
API result to render the HTML result table as described in Table 2.
Table 2: Mapping the result from Graph API into HTML table
HTML Table Column
API service response
Date
The value of the “localDate” and “localTime” attributes that is part of “events” object
Icon
The value of the “images” attribute that is part of the “events” object.
Event
The value of the “name” attribute that is part of the “events” object.
Genre
The value of the “segment” attributes that is part of the “events” object.
V enue
The value of the “name” attribute that is part of the “venue” object inside “events” object.
2.3 Displaying Event Details (Event details)
In the search result table, if the user clicks on the name of an event, the page should request the detailed information using the Event Details API and direct to a section populated with this information, documented at:
https://developer.ticketmaster.com/products-and-docs/apis/discovery-api/v2/#event-details-v2
To retrieve event details, the request needs two parameters (output should be JSON):
• id: ID of the event
• apikey: Your application’s API key. This key identifies your application for purposes of
quota management.
8
2.3.1 Event Details
An example of an HTTP request to the Event Details API is shown below: https://app.ticketmaster.com/discovery/v2/events/{id}?apikey=YOUR_API_KEY&
Figure 8 shows a sample response.
Figure 8: An example of a team photo search response (Keyword: Rams)
The Python script should pass the returned JSON object to the client side or parse the returned JSON and extract useful fields and pass these fields to the client side in JSON-formatted object. You should use JavaScript to parse the JSON object and display the results in a similar format as Figure 9. When clicking on the artist’s name (or team name), a page with artist’s upcoming events will open in a new tab. When clicking on the “Ticketmaster” link, under “Buy Ticket At”, a page to buy tickets online will open in a new page. If the returned JSON stream doesn’t contain certain fields, those fields will not appear on the detail page. A sample output is shown in Figure 9. Figure 9(a) shows a result with all fields, Figure 9(b) shows a result with missing fields such as “artist”, “genre”, “price Range”, and “seat map”.
9
Figure 9(a): An Example of a Valid Search result
Figure 9(b): An Example of a Valid Search result with missing fields
When the search result contains at least one field, you need to map the data extracted from the
API result to render the HTML result table as described in Table 3.
Table 3: Mapping the result from Event Details API into HTML Table
HTML Key
API service response
Date
The value of the “localDate” and “localTime” attributes that is part of the “dates” object
Artist/Team
The value of the “name” attribute that is part of the “attractions” object, segmented by “ | ”
V enue
The value of the “name” attribute that is part of the “venue” object.
Genre
The value of the “subGenre”, “genre”, “segment”, “subType”, and “type” attributes that is part of the “classifications” object, segmented by “ | ”
Price Ranges
The value of the “min” and “max” attributes that are part of
10
the “priceRanges” object, combined with “ -”
Ticket Status
The value of the “status” attribute that is part of the “dates” object.
Buy Ticket At
The value of the “URL” attribute.
Seat Map
The value of the “staticUrl” attribute that is part of the “seatmap” object.
Note that:
• You must use Python to request all JSON objects from Ticketmaster APIs
• You may call Google Geocoding API from client side using JavaScript or from
server using Python
• Do not call ipinfo.io API from Python on the server, as you would get the
location of the server at Google Cloud instead of the location of the user.
• Expanding or hiding sub-areas should be implemented using DOM.
In summary, the search mechanism to be implemented behaves as follows:
• Based on the query in the search form, construct a web service URL to retrieve the output from the Ticketmaster API service.
• Pass the (possibly edited) JSON to the client side and parse JSON using JavaScript.
• Display the events information in the proper format.
3. Hints
3.1 How to get Ticketmaster API Key
• To get a Ticketmaster API key, please follow these steps:
• Create a new account at:
https://developer-acct.ticketmaster.com/user/register
11
Enter your data and click CREATE NEW ACCOUNT. You should receive an e-mail with a link.
Click on the link in the email. You’ll be redirected to the one-time-login. Click LOG IN.
You’ll be redirected to your Profile page where you can select your password.
Select the appropriate time zone, America/Los Angeles.
12
• Once logged in, click your name on the right top corner and select “My Apps”.
• You should see an “approved” app. Expand the app info. You should see a Consumer Key.
That is the key to use with the Ticketmaster APIs.
3.2 How to get Google API Key
• To get a Google API key, please follow these steps:
• Go to the Google Developers Console:
https://console.developers.google.com/flows/enableapi?apiid=geocoding_backend&keyType=SE RVER_SIDE&reusekey=true
• Create a project.
• At the Google APIs’ guide page, click “Get a key” and select a created project.
Note that you should NOT use a google account associated with a USC e-mail. Preferably use a Gmail account.
3.3 Get IPInfo.io API Key
• Go to https://ipinfo.io/ and sign up for free
• A token would be provided after successful sign up
13
An example call is as follows: https://ipinfo.io/?token=YOUR_TOKEN_ID
The following article introduces some similar APIs, so you have more choices for your homework assignment #6, if you wish to try out different APIs:
Use of Freegeoip API is not recommended.
3.4 Deploy Python file to the cloud GAE
You should use the domain name of the GAE service you created in Assignment #5 to make the request. For example, if your GAE server domain is called example.appspot.com, the following links will be generated:
http://example.appspot.com/index.html
The example subdomain in the above URLs will be replaced by your choice of subdomain from the cloud service. You may also use a different page than index.html.
Files to deploy:
client-side files (HTML+CSS+JS)
server-side file (main.py), .yaml, requirements.txt
The project structure should be similar to the following one:
3.5 Parsing JSON-formatted data in Python
Information on how to parse JSON-formatted data in Python is available here:
https://docs.python.org/3/library/json.html
14
If you use your cloud server as a “proxy” pass-through, you do not have to decode and encode the JSON.
4. Files to Submit
In your course homework page, you should update the Homework 6 link to refer to your new initial web search page for this exercise (for example, event.html). Your files must be hosted on GAE cloud service. Graders will verify that this link is indeed pointing to GAE.
Also, submit your source code file to DEN D2L. The timestamp will be used to verify if you used any “grace days.”
**IMPORTANT**:
• All discussions and explanations in Piazza related to this homework are part of the homework description and grading guidelines. So please review all Piazza threads, before finishing the assignment. If there is a conflict between Piazza and this description and/or the grading guidelines, Piazza always rules.
• You can use jQuery for Homework 6 but it is not required.
• You should not call the Ticketmaster APIs directly from JavaScript, bypassing the
Python proxy. Implementing any one of them in JavaScript instead of Python will result in a 4-point penalty. Other APIs can be called from JavaScript.
15