/blog
May 12, 2022

GitHub Search API: An Introduction With Examples

tutorials, github

GitHubis probably the most loved software used by developers all over the world. Besides code collaboration, it brings in tons of useful features, such as issue tracking and code management. And if you've loved what it offers, you'll absolutely love using its raw APIs to build great things.

Being the extensive tool it is, GitHub provides a developer-friendly way to access all of its features via its APIs. One such popular API is the search, which allows developers to search code, users, repositories, issues, labels, pull requests, and much more.

So in this tutorial, I'll walk you through how you can use the GitHub search API to construct queries and search various things on GitHub.

One such popular API is the search, which allows developers to search code, user,s repositories, issues, labels, pull request, and much more.

Working With GitHub APIs

Let's do a quick refresher so you understand how to use GitHub APIs in general. First, make sure you have a GitHub account and have generated a personal access token for authentication.

We'll use a VS Code extension called Thunder Client to test APIs and see their responses. Thunder Client is a tool like Postman that allows you to send HTTP or cURL requests from your editor. It's really simple to use, doesn't appear as overwhelming as Postman, and comes in handy when you're using your editor.

To install this extension, first head over to your VS Code. Then, search "Thunder Client" in the Extensions tab.

github search api vs code

After that, choose the extension and click Install. Since I have already installed the extension, it shows Uninstall for me. But if it's the first time you're opening the extension and don't have the extension yet, it will show Install for you instead.

github search api thunder client

Once that's done, you should see an icon on the left panel of your VS Code. You can click on it to immediately launch Thunder Client.

Let's now make a sample request to one of GitHub's APIs to see if everything is in place. Click on "New Request" in the Thunder Client window.

github searcha api new request

Add the following URL in the request input:

https://api.github.com/users/fuzzysid

Under the Query section, select the Auth tab. Inside this, select the Basic tab. Enter your GitHub username in the Username field. Then add your personal access token in the Password field. Next click Send. You should get back some response that looks like this:

github search api auth

Great! We're all set to test and query GitHub Search APIs directly from our editor.

Search API: An Overview

The easier way to get started with the Search API is to see what all we can search on GitHub. For this, head over to your browser and open api.github.com. Once you do that, you should see a list of all the APIs GitHub offers:

github search api overview with-shadow

As you can see, we can use the search API to search:

  1. Code using code_search_url
  2. Commit using commit_search_url
  3. Issues using issue_search_url
  4. Labels using label_search_url
  5. Repository using repository_search_url
  6. Topic using topic_search_url
  7. User using user_search_url

Notice how each of the URLs follows a similar pattern. There is a common base URL for all the APIs as https://api.github.com/search. Then, there is a search query in each request denoted by ?q=. Finally, there is another query parameter object for pagination and sorting.

In a nutshell, all you need to understand to use Search APIs is how to construct your search queries. So let's see how we can do that with a couple of examples.

github search api look looking

Constructing Search Queries and Search Users

Search queries can't take in as many keywords and qualifiers as you like. You can look at all the available lists of keywords and qualifiers here, but let's start with a simple use case.

We want to search for all the users who have the name "siddhant" in their names.

Here's what the search query would look like:

q=siddhant in:name

We use the in qualifier to search for a term against the name keyword. Let's give this a go.

github search api queries

Notice how we see a list of users with the name "siddhant" in their names. However, there's a small problem with this query. It's giving us both the users as well as organizations in its result. Let's limit the result only to users.

We can do that by adding type:user as another query parameter in the API. So our query now becomes:

q=siddhant in:name type:user

And it yields the following response:

github search api queries

Notice how we got back 1,365 results this time instead of the original 1,366 results. Let's now update our search query further. Let's say that, among these users, we want to find the most popular users. Maybe the top 40 to 50 users who have more than 30 repositories and 10 followers.

We can do that by updating our query as follows:

q=siddhant in:name type:user repos:%3E30+followers:%3E10

And that will give us back our list of popular users:

github search api queries

Awesome! I hope you're getting the hang of constructing queries. Now let's try to search for something else.

Search Code

Let's now see how can search for code on GitHub. Let's say we want to search for some files in a particular repository. How can we do that? What will our search query look like? First, we'll need to update our endpoint from /users to /code.

In this case, let's say we want to look up or search for all the JavaScript files in ReactJS official documentation repository. Here's how we can construct a search query for that:

q=language:js+repo:reactjs/reactjs.org

We specify the repository alongside the organization using the repo keyword. To search for JavaScript files, we specify the language keyword to be of value js.

github search api queries

We can now search for something more specific in the code, say a keyword for a class or a function. Let's say we want to search for the versions keyword. We can simply add that keyword to our query:

q=versions+in:file+language:js+repo:reactjs/reactjs.org

Once we do that, we should now get a list of all those files that have the word "versions" inside them:

github search api queries

Search Commits

Similar to how we searched code and users, we can also search for commits belonging to a particular repository. This time, the endpoint will be /commits instead. The basic query parameter for searching commits is as follows:

q=repo:<REPOSITORY_NAME/ORGANIZATION>+<COMMIT>

We need to first specify the repository name and the organization we want to search the commits from. Then we specify the search query parameter for the commit itself.

Let's search for all the commits in the React documentation repository pertaining to upgrades. So our query now becomes:

q=repo:reactjs/reactjs.org+upgrade

Let's hit this endpoint and see what we get back:

github search api queries

Notice how all the commit messages in the returned list of commits contain the keyword "upgrade." Hence we have searched through all the upgrade-related commits in the React documentation repository.

Search Repositories and Sorting

Now we'll learn how to query or search through repositories on GitHub via the search API. Let's say we want to search for all the popular React libraries written in JavaScript. First, we need to search for all the React and JavaScript-based repositories. The search query for this part looks like this:

q=react+language:js

Then, to reel in the popularity factor, we can sort the result by the number of stars the repository contains. For this, we'll specify the sort parameter as stars and the order parameter as desc. So now the complete search query becomes:

q=react+language:js&sort=stars&order=desc

Great! Now let's test this. If you hit the above endpoint, you'll get back a list of all the React and JavaScript-based repositories sorted in descending order by the number of stars.

github search api queries

Surprisingly, the official React repository comes second in this list after freeCodeCamp! Can you think why is that so? Looks like our popularity criteria need more fine-tuning!

Explore Further

In this tutorial, we have seen how to construct search queries and use GitHub's search API to search users, commits, code, and repositories. However, as I pointed out earlier, there's more you can search through GitHub. The official docs are the best place to start. You can further learn how to search for pull requests, topics, and labels.

Or how about you build a small app that parses the data result by these search APIs for something useful? This app could manifest into an internal tool you can use at work to automate a Github search workflow. It could also turn out to be something interesting that you can use for your own personal or open source projects you contribute to on GitHub. Maybe the client of this app is a powerful integration tool you might need badly!

Before you go...

To stay updated with our latest content, please subscribe to our email updates or follow us on Twitter at @runmedev! Also, check out Runme (interactive runbooks for VS Code), and Runme Cloud.

Let us know what you think. Bye for now! 👋


This post was written by Siddhant Varma. Siddhant is a full-stack JavaScript developer with expertise in frontend engineering. He’s worked with scaling multiple startups in India and has experience building products in the Ed-Tech and healthcare industries. Siddhant has a passion for teaching and a knack for writing. He's also taught programming to many graduates, helping them become better future developers.