jq is a lightweight and flexible command-line JSON processor. It is extremely useful for processing data from APIs to better understand the data your code will be consuming, before you write the code. In this lesson I introduce you to jq and show you the basic features it provides using the Star Wars API (http://swapi.co) as our data source. Topics covered include filtering, piping, object construction and data manipulation.

https://app.egghead.io/api/v1/lessons/misc-using-jq-to-parse-the-star-wars-api/subtitles

Using jq to parse the Star Wars API

[00:01] In this lesson, I'm going to show you how to use the jq utility to filter and parse data from the Star Wars API. Let's start by taking a look at the raw data from the API. There's our data, but it's pretty difficult to read. Let's try that again, and this time pipe it to the jq command and include a simple filter of dot.

[00:21] All the dot does is format and colorize the data, so that it's easier to read. It doesn't modify the response at all. There's our result set, and it's much easier to read. If I scroll back to the top of my result, you can see that it's a JSON object that includes fields for the Count, Next, and Previous URLs, where those exist, and then an array called Results that has a list of the people returned by the API.

[00:45] That's the part we really care about, so let's filter it to just that. In my jq filter, I can specify the name of the object that I want to filter on, and executing it returns just that object. I scroll back up to look at the beginning of the output. You can see that the response started at the Results array. I can also filter on a specific item within the array, for example, the first item, and we get Luke Skywalker returned.

[01:09] I can use jq to create a new object, for example, one that contains his name, birth year, and gender, by creating an additional jq filter, and then creating a new object with Name that's going to pull the value from the Name field in the object. Birthday is going to pull the value from the Birth Year attribute, and gender will get its value from the Gender attribute.

[01:33] This same pattern will work for all the items returned in the results array by removing the filter for index item zero. That works for any object, including arrays. For example, the list of vehicles that Luke Skywalker owns can be returned, as well.

[01:51] If we look at the Luke Skywalker object again, we see that his height is listed as 172, but I'm from the United States, so I have no idea how tall 172 centimeters actually is. Let's use jq to convert that into inches. I can filter my response to just the height value, and I can multiply that value times 039370, which will convert centimeters to inches.

[02:16] I get 172 back, so if we take a look at this API documentation, specifically the people object, and scroll down to the attributes, it says that height is a string. To further illustrate what jq did with that, instead of multiplying time 039370, I can multiply times 2, and the response is 172, 172, which indicate they treated it just as a string, which was expected.

[02:42] Knowing that, I can include one more filter and call it to number function, and multiply that times 039370. When that executes, I learn that Luke Skywalker is actually 67 inches tall.

Using jq to parse the Star Wars API

Share this video with your friends