Search

Note: The topics property for repositories on GitHub is currently available for developers to preview. To view the topics property in calls that return repository results, you must provide a custom media type in the Accept header:

application/vnd.github.mercy-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

About the search API

The Search API is optimized to help you find the specific item you're looking for (e.g., a specific user, a specific file in a repository, etc.). Think of it the way you think of performing a search on Google. It's designed to help you find the one result you're looking for (or maybe the few results you're looking for). Just like searching on Google, you sometimes want to see a few pages of search results so that you can find the item that best meets your needs. To satisfy that need, the GitHub Search API provides up to 1,000 results for each search.

Ranking search results

Unless another sort option is provided as a query parameter, results are sorted by best match, as indicated by the score field for each item returned. This is a computed value representing the relevance of an item relative to the other items in the result set. Multiple factors are combined to boost the most relevant item to the top of the result list.

Rate limit

The Search API has a custom rate limit. For requests using Basic Authentication, OAuth, or client ID and secret, you can make up to 30 requests per minute. For unauthenticated requests, the rate limit allows you to make up to 10 requests per minute.

See the rate limit documentation for details on determining your current rate limit status.

Timeouts and incomplete results

To keep the Search API fast for everyone, we limit how long any individual query can run. For queries that exceed the time limit, the API returns the matches that were already found prior to the timeout, and the response has the incomplete_results property set to true.

Reaching a timeout does not necessarily mean that search results are incomplete. More results might have been found, but also might not.

Search repositories

Note: The topics property for repositories on GitHub is currently available for developers to preview. To view the topics property in calls that return repository results, you must provide a custom media type in the Accept header:

application/vnd.github.mercy-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Find repositories via various criteria. This method returns up to 100 results per page.

GET /search/repositories

Parameters

Name Type Description
q string Required. The search keywords, as well as any qualifiers.
sort string The sort field. One of stars, forks, or updated. Default: results are sorted by best match.
order string The sort order if sort parameter is provided. One of asc or desc. Default: desc

The q search term can also contain any combination of the supported repository search qualifiers as described by the in-browser repository search documentation and search syntax documentation:

  • created or pushed Filters repositories based on date of creation, or when they were last updated.
  • fork Filters whether forked repositories should be included (true) or only forked repositories should be returned (only).
  • forks Filters repositories based on the number of forks.
  • in Qualifies which fields are searched. With this qualifier you can restrict the search to just the repository name, description, readme, or any combination of these.
  • language Searches repositories based on the language they're written in.
  • license Filters repositories by license or license family, using the license keyword.
  • repo or user Limits searches to a specific repository or user.
  • size Finds repositories that match a certain size (in kilobytes).
  • stars Searches repositories based on the number of stars.
  • topic Filters repositories based on the specified topic.
  • archived Filters whether archived repositories should be included (true) or not (false).

Example

Suppose you want to search for popular Tetris repositories written in Assembly. Your query might look like this.

curl https://api.github.com/search/repositories?q=tetris+language:assembly&sort=stars&order=desc

You can search for multiple topics by adding more topic: instances, and including the mercy-preview header. For example:

curl -H "Accept: application/vnd.github.mercy-preview+json" \
https://api.github.com/search/repositories?q=topic:ruby+topic:rails

In this request, we're searching for repositories with the word tetris in the name, the description, or the README. We're limiting the results to only find repositories where the primary language is Assembly. We're sorting by stars in descending order, so that the most popular repositories appear first in the search results.

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

{
  "total_count": 40,
  "incomplete_results": false,
  "items": [
    {
      "id": 3081286,
      "node_id": "MDEwOlJlcG9zaXRvcnkzMDgxMjg2",
      "name": "Tetris",
      "full_name": "dtrupenn/Tetris",
      "owner": {
        "login": "dtrupenn",
        "id": 872147,
        "node_id": "MDQ6VXNlcjg3MjE0Nw==",
        "avatar_url": "https://secure.gravatar.com/avatar/e7956084e75f239de85d3a31bc172ace?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png",
        "gravatar_id": "",
        "url": "https://api.github.com/users/dtrupenn",
        "received_events_url": "https://api.github.com/users/dtrupenn/received_events",
        "type": "User"
      },
      "private": false,
      "html_url": "https://github.com/dtrupenn/Tetris",
      "description": "A C implementation of Tetris using Pennsim through LC4",
      "fork": false,
      "url": "https://api.github.com/repos/dtrupenn/Tetris",
      "created_at": "2012-01-01T00:31:50Z",
      "updated_at": "2013-01-05T17:58:47Z",
      "pushed_at": "2012-01-01T00:37:02Z",
      "homepage": "",
      "size": 524,
      "stargazers_count": 1,
      "watchers_count": 1,
      "language": "Assembly",
      "forks_count": 0,
      "open_issues_count": 0,
      "master_branch": "master",
      "default_branch": "master",
      "score": 10.309712
    }
  ]
}

Highlighting repository search results

You might want to highlight the matching search terms when displaying search results. The API offers additional metadata to support this use case. To get this metadata in your search results, specify the text-match media type in your Accept header. For example, via cURL, the above query would look like this:

curl -H 'Accept: application/vnd.github.v3.text-match+json' \
'https://api.github.com/search/repositories?q=tetris+language:assembly&sort=stars&order=desc'

This produces the same JSON payload as above, with an extra key called text_matches, an array of objects. These objects provide information such as the position of your search terms within the text, as well as the property that included the search term.

When searching for repositories, you can get text match metadata for the name and description fields. For details on the attributes present in the text_matches array, see text match metadata.

Here's an example response:

{
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/3081286",
      "object_type": "Repository",
      "property": "name",
      "fragment": "Tetris",
      "matches": [
        {
          "text": "Tetris",
          "indices": [
            0,
            6
          ]
        }
      ]
    },
    {
      "object_url": "https://api.github.com/repositories/3081286",
      "object_type": "Repository",
      "property": "description",
      "fragment": "A C implementation of Tetris using Pennsim through LC4",
      "matches": [
        {
          "text": "Tetris",
          "indices": [
            22,
            28
          ]
        }
      ]
    }
  ]
}

Search commits

The Commit Search API is currently available for developers to preview. During the preview period, the APIs may change without advance notice. Please see the blog post for full details.

To access the API you must provide a custom media type in the Accept header:

  application/vnd.github.cloak-preview

Find commits via various criteria. This method returns up to 100 results per page.

GET /search/commits

Considerations for commit search

Only the default branch is considered. In most cases, this will be the master branch.

Parameters

Name Type Description
q string Required. The search terms.
sort string The sort field. Can be author-date or committer-date. Default: results are sorted by best match.
order string The sort order if sort parameter is provided. One of asc or desc. Default: desc

The q search term can also contain any combination of the supported commit search qualifiers as described by the in-browser commit search documentation and search syntax documentation:

  • author Matches commits authored by a user (based on email settings).
  • committer Matches commits committed by a user (based on email settings).
  • author-name Matches commits by author name.
  • committer-name Matches commits by committer name.
  • author-email Matches commits by author email.
  • committer-email Matches commits by committer email.
  • author-date Matches commits by author date range.
  • committer-date Matches commits by committer date range.
  • merge true filters to merge commits, false filters out merge commits.
  • hash Matches commits by hash.
  • parent Matches commits that have a particular parent.
  • tree Matches commits by tree hash.
  • is Matches public or private repositories.
  • user, org, or repo Limits searches to a specific user, organization, or repository.

Example

Suppose you want to find commits related to CSS in the octocat/Spoon-Knife repository. Your query would look something like this:

curl -H "Accept: application/vnd.github.cloak-preview" \
https://api.github.com/search/commits?q=repo:octocat/Spoon-Knife+css

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

{
  "total_count": 1,
  "incomplete_results": false,
  "items": [
    {
      "url": "https://api.github.com/repos/octocat/Spoon-Knife/commits/bb4cc8d3b2e14b3af5df699876dd4ff3acd00b7f",
      "sha": "bb4cc8d3b2e14b3af5df699876dd4ff3acd00b7f",
      "html_url": "https://github.com/octocat/Spoon-Knife/commit/bb4cc8d3b2e14b3af5df699876dd4ff3acd00b7f",
      "comments_url": "https://api.github.com/repos/octocat/Spoon-Knife/commits/bb4cc8d3b2e14b3af5df699876dd4ff3acd00b7f/comments",
      "commit": {
        "url": "https://api.github.com/repos/octocat/Spoon-Knife/git/commits/bb4cc8d3b2e14b3af5df699876dd4ff3acd00b7f",
        "author": {
          "date": "2014-02-04T14:38:36-08:00",
          "name": "The Octocat",
          "email": "octocat@nowhere.com"
        },
        "committer": {
          "date": "2014-02-12T15:18:55-08:00",
          "name": "The Octocat",
          "email": "octocat@nowhere.com"
        },
        "message": "Create styles.css and updated README",
        "tree": {
          "url": "https://api.github.com/repos/octocat/Spoon-Knife/git/trees/a639e96f9038797fba6e0469f94a4b0cc459fa68",
          "sha": "a639e96f9038797fba6e0469f94a4b0cc459fa68"
        },
        "comment_count": 8
      },
      "author": {
        "login": "octocat",
        "id": 583231,
        "node_id": "MDQ6VXNlcjU4MzIzMQ==",
        "avatar_url": "https://avatars.githubusercontent.com/u/583231?v=3",
        "gravatar_id": "",
        "url": "https://api.github.com/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      },
      "committer": {
        "login": "octocat",
        "id": 583231,
        "node_id": "MDQ6VXNlcjU4MzIzMQ==",
        "avatar_url": "https://avatars.githubusercontent.com/u/583231?v=3",
        "gravatar_id": "",
        "url": "https://api.github.com/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      },
      "parents": [
        {
          "url": "https://api.github.com/repos/octocat/Spoon-Knife/commits/a30c19e3f13765a3b48829788bc1cb8b4e95cee4",
          "html_url": "https://github.com/octocat/Spoon-Knife/commit/a30c19e3f13765a3b48829788bc1cb8b4e95cee4",
          "sha": "a30c19e3f13765a3b48829788bc1cb8b4e95cee4"
        }
      ],
      "repository": {
        "id": 1300192,
        "node_id": "MDEwOlJlcG9zaXRvcnkxMzAwMTky",
        "name": "Spoon-Knife",
        "full_name": "octocat/Spoon-Knife",
        "owner": {
          "login": "octocat",
          "id": 583231,
          "node_id": "MDQ6VXNlcjU4MzIzMQ==",
          "avatar_url": "https://avatars.githubusercontent.com/u/583231?v=3",
          "gravatar_id": "",
          "url": "https://api.github.com/users/octocat",
          "html_url": "https://github.com/octocat",
          "followers_url": "https://api.github.com/users/octocat/followers",
          "following_url": "https://api.github.com/users/octocat/following{/other_user}",
          "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
          "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
          "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
          "organizations_url": "https://api.github.com/users/octocat/orgs",
          "repos_url": "https://api.github.com/users/octocat/repos",
          "events_url": "https://api.github.com/users/octocat/events{/privacy}",
          "received_events_url": "https://api.github.com/users/octocat/received_events",
          "type": "User",
          "site_admin": false
        },
        "private": false,
        "html_url": "https://github.com/octocat/Spoon-Knife",
        "description": "This repo is for demonstration purposes only.",
        "fork": false,
        "url": "https://api.github.com/repos/octocat/Spoon-Knife",
        "forks_url": "https://api.github.com/repos/octocat/Spoon-Knife/forks",
        "keys_url": "https://api.github.com/repos/octocat/Spoon-Knife/keys{/key_id}",
        "collaborators_url": "https://api.github.com/repos/octocat/Spoon-Knife/collaborators{/collaborator}",
        "teams_url": "https://api.github.com/repos/octocat/Spoon-Knife/teams",
        "hooks_url": "https://api.github.com/repos/octocat/Spoon-Knife/hooks",
        "issue_events_url": "https://api.github.com/repos/octocat/Spoon-Knife/issues/events{/number}",
        "events_url": "https://api.github.com/repos/octocat/Spoon-Knife/events",
        "assignees_url": "https://api.github.com/repos/octocat/Spoon-Knife/assignees{/user}",
        "branches_url": "https://api.github.com/repos/octocat/Spoon-Knife/branches{/branch}",
        "tags_url": "https://api.github.com/repos/octocat/Spoon-Knife/tags",
        "blobs_url": "https://api.github.com/repos/octocat/Spoon-Knife/git/blobs{/sha}",
        "git_tags_url": "https://api.github.com/repos/octocat/Spoon-Knife/git/tags{/sha}",
        "git_refs_url": "https://api.github.com/repos/octocat/Spoon-Knife/git/refs{/sha}",
        "trees_url": "https://api.github.com/repos/octocat/Spoon-Knife/git/trees{/sha}",
        "statuses_url": "https://api.github.com/repos/octocat/Spoon-Knife/statuses/{sha}",
        "languages_url": "https://api.github.com/repos/octocat/Spoon-Knife/languages",
        "stargazers_url": "https://api.github.com/repos/octocat/Spoon-Knife/stargazers",
        "contributors_url": "https://api.github.com/repos/octocat/Spoon-Knife/contributors",
        "subscribers_url": "https://api.github.com/repos/octocat/Spoon-Knife/subscribers",
        "subscription_url": "https://api.github.com/repos/octocat/Spoon-Knife/subscription",
        "commits_url": "https://api.github.com/repos/octocat/Spoon-Knife/commits{/sha}",
        "git_commits_url": "https://api.github.com/repos/octocat/Spoon-Knife/git/commits{/sha}",
        "comments_url": "https://api.github.com/repos/octocat/Spoon-Knife/comments{/number}",
        "issue_comment_url": "https://api.github.com/repos/octocat/Spoon-Knife/issues/comments{/number}",
        "contents_url": "https://api.github.com/repos/octocat/Spoon-Knife/contents/{+path}",
        "compare_url": "https://api.github.com/repos/octocat/Spoon-Knife/compare/{base}...{head}",
        "merges_url": "https://api.github.com/repos/octocat/Spoon-Knife/merges",
        "archive_url": "https://api.github.com/repos/octocat/Spoon-Knife/{archive_format}{/ref}",
        "downloads_url": "https://api.github.com/repos/octocat/Spoon-Knife/downloads",
        "issues_url": "https://api.github.com/repos/octocat/Spoon-Knife/issues{/number}",
        "pulls_url": "https://api.github.com/repos/octocat/Spoon-Knife/pulls{/number}",
        "milestones_url": "https://api.github.com/repos/octocat/Spoon-Knife/milestones{/number}",
        "notifications_url": "https://api.github.com/repos/octocat/Spoon-Knife/notifications{?since,all,participating}",
        "labels_url": "https://api.github.com/repos/octocat/Spoon-Knife/labels{/name}",
        "releases_url": "https://api.github.com/repos/octocat/Spoon-Knife/releases{/id}",
        "deployments_url": "https://api.github.com/repos/octocat/Spoon-Knife/deployments"
      },
      "score": 4.9971514
    }
  ]
}

Highlighting code search results

When searching for commits, you can get text match metadata for the message field. See the section on text match metadata for full details.

Search code

Find file contents via various criteria. This method returns up to 100 results per page.

GET /search/code

Note: You must authenticate to search for code across all public repositories.

Considerations for code search

Due to the complexity of searching code, there are a few restrictions on how searches are performed:

  • Only the default branch is considered. In most cases, this will be the master branch.
  • Only files smaller than 384 KB are searchable.
  • You must always include at least one search term when searching source code. For example, searching for language:go is not valid, while amazing language:go is.

Parameters

Name Type Description
q string Required. The search terms.
sort string The sort field. Can only be indexed, which indicates how recently a file has been indexed by the GitHub search infrastructure. Default: results are sorted by best match.
order string The sort order if sort parameter is provided. One of asc or desc. Default: desc

The q search term can also contain any combination of the supported code search qualifiers as described by the in-browser code search documentation and search syntax documentation:

  • in Qualifies which fields are searched. With this qualifier you can restrict the search to the file contents (file), the file path (path), or both.
  • language Searches code based on the language it's written in.
  • fork Specifies that code from forked repositories should be searched (true). Repository forks will not be searchable unless the fork has more stars than the parent repository.
  • size Finds files that match a certain size (in bytes).
  • path Specifies the path prefix that the resulting file must be under.
  • filename Matches files by a substring of the filename.
  • extension Matches files with a certain extension after a dot.
  • user or repo Limits searches to a specific user or repository.

Example

Suppose you want to find the definition of the addClass function inside jQuery. Your query would look something like this:

curl https://api.github.com/search/code?q=addClass+in:file+language:js+repo:jquery/jquery

Here, we're searching for the keyword addClass within a file's contents. We're making sure that we're only looking in files where the language is JavaScript. And we're scoping the search to the repo:jquery/jquery repository.

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

{
  "total_count": 7,
  "incomplete_results": false,
  "items": [
    {
      "name": "classes.js",
      "path": "src/attributes/classes.js",
      "sha": "d7212f9dee2dcc18f084d7df8f417b80846ded5a",
      "url": "https://api.github.com/repositories/167174/contents/src/attributes/classes.js?ref=825ac3773694e0cd23ee74895fd5aeb535b27da4",
      "git_url": "https://api.github.com/repositories/167174/git/blobs/d7212f9dee2dcc18f084d7df8f417b80846ded5a",
      "html_url": "https://github.com/jquery/jquery/blob/825ac3773694e0cd23ee74895fd5aeb535b27da4/src/attributes/classes.js",
      "repository": {
        "id": 167174,
        "node_id": "MDEwOlJlcG9zaXRvcnkxNjcxNzQ=",
        "name": "jquery",
        "full_name": "jquery/jquery",
        "owner": {
          "login": "jquery",
          "id": 70142,
          "node_id": "MDQ6VXNlcjcwMTQy",
          "avatar_url": "https://0.gravatar.com/avatar/6906f317a4733f4379b06c32229ef02f?d=https%3A%2F%2Fidenticons.github.com%2Ff426f04f2f9813718fb806b30e0093de.png",
          "gravatar_id": "",
          "url": "https://api.github.com/users/jquery",
          "html_url": "https://github.com/jquery",
          "followers_url": "https://api.github.com/users/jquery/followers",
          "following_url": "https://api.github.com/users/jquery/following{/other_user}",
          "gists_url": "https://api.github.com/users/jquery/gists{/gist_id}",
          "starred_url": "https://api.github.com/users/jquery/starred{/owner}{/repo}",
          "subscriptions_url": "https://api.github.com/users/jquery/subscriptions",
          "organizations_url": "https://api.github.com/users/jquery/orgs",
          "repos_url": "https://api.github.com/users/jquery/repos",
          "events_url": "https://api.github.com/users/jquery/events{/privacy}",
          "received_events_url": "https://api.github.com/users/jquery/received_events",
          "type": "Organization",
          "site_admin": false
        },
        "private": false,
        "html_url": "https://github.com/jquery/jquery",
        "description": "jQuery JavaScript Library",
        "fork": false,
        "url": "https://api.github.com/repos/jquery/jquery",
        "forks_url": "https://api.github.com/repos/jquery/jquery/forks",
        "keys_url": "https://api.github.com/repos/jquery/jquery/keys{/key_id}",
        "collaborators_url": "https://api.github.com/repos/jquery/jquery/collaborators{/collaborator}",
        "teams_url": "https://api.github.com/repos/jquery/jquery/teams",
        "hooks_url": "https://api.github.com/repos/jquery/jquery/hooks",
        "issue_events_url": "https://api.github.com/repos/jquery/jquery/issues/events{/number}",
        "events_url": "https://api.github.com/repos/jquery/jquery/events",
        "assignees_url": "https://api.github.com/repos/jquery/jquery/assignees{/user}",
        "branches_url": "https://api.github.com/repos/jquery/jquery/branches{/branch}",
        "tags_url": "https://api.github.com/repos/jquery/jquery/tags",
        "blobs_url": "https://api.github.com/repos/jquery/jquery/git/blobs{/sha}",
        "git_tags_url": "https://api.github.com/repos/jquery/jquery/git/tags{/sha}",
        "git_refs_url": "https://api.github.com/repos/jquery/jquery/git/refs{/sha}",
        "trees_url": "https://api.github.com/repos/jquery/jquery/git/trees{/sha}",
        "statuses_url": "https://api.github.com/repos/jquery/jquery/statuses/{sha}",
        "languages_url": "https://api.github.com/repos/jquery/jquery/languages",
        "stargazers_url": "https://api.github.com/repos/jquery/jquery/stargazers",
        "contributors_url": "https://api.github.com/repos/jquery/jquery/contributors",
        "subscribers_url": "https://api.github.com/repos/jquery/jquery/subscribers",
        "subscription_url": "https://api.github.com/repos/jquery/jquery/subscription",
        "commits_url": "https://api.github.com/repos/jquery/jquery/commits{/sha}",
        "git_commits_url": "https://api.github.com/repos/jquery/jquery/git/commits{/sha}",
        "comments_url": "https://api.github.com/repos/jquery/jquery/comments{/number}",
        "issue_comment_url": "https://api.github.com/repos/jquery/jquery/issues/comments/{number}",
        "contents_url": "https://api.github.com/repos/jquery/jquery/contents/{+path}",
        "compare_url": "https://api.github.com/repos/jquery/jquery/compare/{base}...{head}",
        "merges_url": "https://api.github.com/repos/jquery/jquery/merges",
        "archive_url": "https://api.github.com/repos/jquery/jquery/{archive_format}{/ref}",
        "downloads_url": "https://api.github.com/repos/jquery/jquery/downloads",
        "issues_url": "https://api.github.com/repos/jquery/jquery/issues{/number}",
        "pulls_url": "https://api.github.com/repos/jquery/jquery/pulls{/number}",
        "milestones_url": "https://api.github.com/repos/jquery/jquery/milestones{/number}",
        "notifications_url": "https://api.github.com/repos/jquery/jquery/notifications{?since,all,participating}",
        "labels_url": "https://api.github.com/repos/jquery/jquery/labels{/name}"
      },
      "score": 0.5269679
    }
  ]
}

Highlighting code search results

You might want to highlight the matching search terms when displaying search results. The API offers additional metadata to support this use case. To get this metadata in your search results, specify the text-match media type in your Accept header. For example, via cURL, the above query would look like this:

curl -H 'Accept: application/vnd.github.v3.text-match+json' \
https://api.github.com/search/code?q=addClass+in:file+language:js+repo:jquery/jquery

This produces the same JSON payload as above, with an extra key called text_matches, an array of objects. These objects provide information such as the position of your search terms within the text, as well as the property that included the search term.

When searching for code, you can get text match metadata for the file content and file path fields. For details on the attributes present in the text_matches array, see text match metadata.

Here's an example response:

{
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/167174/contents/src/attributes/classes.js?ref=825ac3773694e0cd23ee74895fd5aeb535b27da4",
      "object_type": "FileContent",
      "property": "content",
      "fragment": ";\n\njQuery.fn.extend({\n\taddClass: function( value ) {\n\t\tvar classes, elem, cur, clazz, j, finalValue",
      "matches": [
        {
          "text": "addClass",
          "indices": [
            23,
            31
          ]
        }
      ]
    },
    {
      "object_url": "https://api.github.com/repositories/167174/contents/src/attributes/classes.js?ref=825ac3773694e0cd23ee74895fd5aeb535b27da4",
      "object_type": "FileContent",
      "property": "content",
      "fragment": ".isFunction( value ) ) {\n\t\t\treturn this.each(function( j ) {\n\t\t\t\tjQuery( this ).addClass( value.call( this",
      "matches": [
        {
          "text": "addClass",
          "indices": [
            80,
            88
          ]
        }
      ]
    }
  ]
}

Search issues

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Find issues by state and keyword. This method returns up to 100 results per page.

GET /search/issues

Parameters

Name Type Description
q string Required. The search terms.
sort string The sort field. Can be comments, created, or updated. Default: results are sorted by best match.
order string The sort order if sort parameter is provided. One of asc or desc. Default: desc

The q search term can also contain any combination of the supported issue search qualifiers as described by the in-browser issue search documentation and search syntax documentation:

  • type With this qualifier you can restrict the search to issues (issue) or pull request (pr) only.
  • in Qualifies which fields are searched. With this qualifier you can restrict the search to just the title (title), body (body), comments (comments), or any combination of these.
  • author Finds issues or pull requests created by a certain user.
  • assignee Finds issues or pull requests that are assigned to a certain user.
  • mentions Finds issues or pull requests that mention a certain user.
  • commenter Finds issues or pull requests that a certain user commented on.
  • involves Finds issues or pull requests that were either created by a certain user, assigned to that user, mention that user, or were commented on by that user.
  • team For organizations you're a member of, finds issues or pull requests that @mention a team within the organization.
  • state Filter issues or pull requests based on whether they're open or closed.
  • labels Filters issues or pull requests based on their labels.
  • no Filters items missing certain metadata, such as label, milestone, or assignee
  • language Searches for issues or pull requests within repositories that match a certain language.
  • is Searches for items within repositories that match a certain state, such as open, closed, or merged
  • created or updated Filters issues or pull requests based on date of creation, or when they were last updated.
  • merged Filters pull requests based on the date when they were merged.
  • status Filters pull requests based on the commit status.
  • head or base Filters pull requests based on the branch that they came from or that they are modifying.
  • closed Filters issues or pull requests based on the date when they were closed.
  • comments Filters issues or pull requests based on the quantity of comments.
  • user or repo Limits searches to a specific user or repository.
  • project Limits searches to a specific project board in a repository or organization.
  • archived Filters issues or pull requests based on whether they are in an archived repository.

If you know the specific SHA hash of a commit, you can use also use it to search for pull requests that contain that SHA. Note that the SHA syntax must be at least seven characters.

Example

Let's say you want to find the oldest unresolved Python bugs on Windows. Your query might look something like this.

curl https://api.github.com/search/issues?q=windows+label:bug+language:python+state:open&sort=created&order=asc

In this query, we're searching for the keyword windows, within any open issue that's labeled as bug. The search runs across repositories whose primary language is Python. We’re sorting by creation date in ascending order, so that the oldest issues appear first in the search results.

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

{
  "total_count": 280,
  "incomplete_results": false,
  "items": [
    {
      "url": "https://api.github.com/repos/batterseapower/pinyin-toolkit/issues/132",
      "repository_url": "https://api.github.com/repos/batterseapower/pinyin-toolkit",
      "labels_url": "https://api.github.com/repos/batterseapower/pinyin-toolkit/issues/132/labels{/name}",
      "comments_url": "https://api.github.com/repos/batterseapower/pinyin-toolkit/issues/132/comments",
      "events_url": "https://api.github.com/repos/batterseapower/pinyin-toolkit/issues/132/events",
      "html_url": "https://github.com/batterseapower/pinyin-toolkit/issues/132",
      "id": 35802,
      "node_id": "MDU6SXNzdWUzNTgwMg==",
      "number": 132,
      "title": "Line Number Indexes Beyond 20 Not Displayed",
      "user": {
        "login": "Nick3C",
        "id": 90254,
        "node_id": "MDQ6VXNlcjkwMjU0",
        "avatar_url": "https://secure.gravatar.com/avatar/934442aadfe3b2f4630510de416c5718?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png",
        "gravatar_id": "",
        "url": "https://api.github.com/users/Nick3C",
        "html_url": "https://github.com/Nick3C",
        "followers_url": "https://api.github.com/users/Nick3C/followers",
        "following_url": "https://api.github.com/users/Nick3C/following{/other_user}",
        "gists_url": "https://api.github.com/users/Nick3C/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/Nick3C/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/Nick3C/subscriptions",
        "organizations_url": "https://api.github.com/users/Nick3C/orgs",
        "repos_url": "https://api.github.com/users/Nick3C/repos",
        "events_url": "https://api.github.com/users/Nick3C/events{/privacy}",
        "received_events_url": "https://api.github.com/users/Nick3C/received_events",
        "type": "User"
      },
      "labels": [
        {
          "id": 4,
          "node_id": "MDU6TGFiZWw0",
          "url": "https://api.github.com/repos/batterseapower/pinyin-toolkit/labels/bug",
          "name": "bug",
          "color": "ff0000"
        }
      ],
      "state": "open",
      "assignee": null,
      "milestone": null,
      "comments": 15,
      "created_at": "2009-07-12T20:10:41Z",
      "updated_at": "2009-07-19T09:23:43Z",
      "closed_at": null,
      "pull_request": {
        "html_url": null,
        "diff_url": null,
        "patch_url": null
      },
      "body": "...",
      "score": 1.3859273
    }
  ]
}

Highlighting issue search results

You might want to highlight the matching search terms when displaying search results. The API offers additional metadata to support this use case. To get this metadata in your search results, specify the text-match media type in your Accept header. For example, via cURL, the above query would look like this:

curl -H 'Accept: application/vnd.github.v3.text-match+json' \
'https://api.github.com/search/issues?q=windows+label:bug+language:python+state:open&sort=created&order=asc'

This produces the same JSON payload as above, with an extra key called text_matches, an array of objects. These objects provide information such as the position of your search terms within the text, as well as the property that included the search term.

When searching for issues, you can get text match metadata for the issue title, issue body, and issue comment body fields. For details on the attributes present in the text_matches array, see text match metadata.

Here's an example response:

{
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/215335/issues/132",
      "object_type": "Issue",
      "property": "body",
      "fragment": "comprehensive windows font I know of).\n\nIf we can find a commonly distributed windows font that supports them then no problem (we can use html font tags) but otherwise the '(21)' style is probably better.\n",
      "matches": [
        {
          "text": "windows",
          "indices": [
            14,
            21
          ]
        },
        {
          "text": "windows",
          "indices": [
            78,
            85
          ]
        }
      ]
    },
    {
      "object_url": "https://api.github.com/repositories/215335/issues/comments/25688",
      "object_type": "IssueComment",
      "property": "body",
      "fragment": " right after that are a bit broken IMHO :). I suppose we could have some hack that maxes out at whatever the font does...\n\nI'll check what the state of play is on Windows.\n",
      "matches": [
        {
          "text": "Windows",
          "indices": [
            163,
            170
          ]
        }
      ]
    }
  ]
}

Search users

Find users via various criteria. This method returns up to 100 results per page.

GET /search/users

Parameters

Name Type Description
q string Required. The search terms.
sort string The sort field. Can be followers, repositories, or joined. Default: results are sorted by best match.
order string The sort order if sort parameter is provided. One of asc or desc. Default: desc

The q search term can also contain any combination of the supported user search qualifiers as described by the in-browser user search documentation and search syntax documentation:

  • type With this qualifier you can restrict the search to just personal accounts (user) or just organization accounts (org).
  • in Qualifies which fields are searched. With this qualifier you can restrict the search to just the username (login), public email (email), full name (fullname), or any combination of these.
  • repos Filters users based on the number of repositories they have.
  • location Filter users by the location indicated in their profile.
  • language Search for users that have repositories that match a certain language.
  • created Filter users based on when they joined.
  • followers Filter users based on the number of followers they have.

Example

Imagine you're looking for a list of popular users. You might try out this query:

curl https://api.github.com/search/users?q=tom+repos:%3E42+followers:%3E1000

Here, we're looking at users with the name Tom. We're only interested in those with more than 42 repositories, and only if they have over 1,000 followers.

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

{
  "total_count": 12,
  "incomplete_results": false,
  "items": [
    {
      "login": "mojombo",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://secure.gravatar.com/avatar/25c7c18223fb42a4c6ae1c8db6f50f9b?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png",
      "gravatar_id": "",
      "url": "https://api.github.com/users/mojombo",
      "html_url": "https://github.com/mojombo",
      "followers_url": "https://api.github.com/users/mojombo/followers",
      "subscriptions_url": "https://api.github.com/users/mojombo/subscriptions",
      "organizations_url": "https://api.github.com/users/mojombo/orgs",
      "repos_url": "https://api.github.com/users/mojombo/repos",
      "received_events_url": "https://api.github.com/users/mojombo/received_events",
      "type": "User",
      "score": 105.47857
    }
  ]
}

Highlighting user search results

You might want to highlight the matching search terms when displaying search results. The API offers additional metadata to support this use case. To get this metadata in your search results, specify the text-match media type in your Accept header. For example, via cURL, the above query would look like this:

curl -H 'Accept: application/vnd.github.v3.text-match+json' \
https://api.github.com/search/users?q=tom+repos:%3E42+followers:%3E1000

This produces the same JSON payload as above, with an extra key called text_matches, an array of objects. These objects provide information such as the position of your search terms within the text, as well as the property that included the search term.

When searching for users, you can get text match metadata for the issue login, email, and name fields. For details on the attributes present in the text_matches array, see text match metadata.

{
  "text_matches": [
    {
      "object_url": "https://api.github.com/users/mojombo",
      "object_type": "User",
      "property": "email",
      "fragment": "tom@github.com",
      "matches": [
        {
          "text": "tom",
          "indices": [
            0,
            3
          ]
        }
      ]
    },
    {
      "object_url": "https://api.github.com/users/mojombo",
      "object_type": "User",
      "property": "name",
      "fragment": "Tom Preston-Werner",
      "matches": [
        {
          "text": "Tom",
          "indices": [
            0,
            3
          ]
        }
      ]
    }
  ]
}

Search topics

Note: The topics property for repositories on GitHub is currently available for developers to preview. To view the topics property in calls that return repository results, you must provide a custom media type in the Accept header:

application/vnd.github.mercy-preview+json

Find topics via various criteria. This method returns up to 100 results per page.

GET /search/topics

Parameters

Name Type Description
q string Required. The search terms.

Results are sorted by best match by default.

The q search term can also contain any combination of the supported topic search qualifiers as described by the in-browser topic search documentation and search syntax documentation:

  • is:curated Finds topics that have extra information, e.g., a description, display name, or logo, because they have an entry in the github/explore repository.
  • is:featured Finds topics listed on https://github.com/topics. Any featured topic will also be curated.
  • is:not-featured Finds topics not listed on https://github.com/topics.
  • is:not-curated Finds topics that have no extra information because they haven't been added to the github/explore repository.
  • repositories: Finds topics with some number of repositories using them, e.g., repositories:>1000.

Example

Suppose you want to search for topics related to Ruby that are featured on https://github.com/topics. Your query might look like this:

curl -H 'Accept: application/vnd.github.mercy-preview+json' \
'https://api.github.com/search/topics?q=ruby+is:featured'

In this request, we're searching for topics with the keyword ruby, and we're limiting the results to find only topics that are featured. The topics that are the best match for the query appear first in the search results.

Note: A search for featured Ruby topics only has 6 total results, so a Link header indicating pagination is not included in the response.

Status: 200 OK
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

{
  "total_count": 6,
  "incomplete_results": false,
  "items": [
    {
      "name": "ruby",
      "display_name": "Ruby",
      "short_description": "Ruby is a scripting language designed for simplified object-oriented programming.",
      "description": "Ruby was developed by Yukihiro \"Matz\" Matsumoto in 1995 with the intent of having an easily readable programming language. It is integrated with the Rails framework to create dynamic web-applications. Ruby's syntax is similar to that of Perl and Python.",
      "created_by": "Yukihiro Matsumoto",
      "released": "December 21, 1995",
      "created_at": "2016-11-28T22:03:59Z",
      "updated_at": "2017-10-30T18:16:32Z",
      "featured": true,
      "curated": true,
      "score": 1750.5872
    },
    {
      "name": "rails",
      "display_name": "Rails",
      "short_description": "Ruby on Rails (Rails) is a web application framework written in Ruby.",
      "description": "Ruby on Rails (Rails) is a web application framework written in Ruby. It is meant to help simplify the building of complex websites.",
      "created_by": "David Heinemeier Hansson",
      "released": "December 13 2005",
      "created_at": "2016-12-09T17:03:50Z",
      "updated_at": "2017-10-30T16:20:19Z",
      "featured": true,
      "curated": true,
      "score": 192.49863
    },
    {
      "name": "python",
      "display_name": "Python",
      "short_description": "Python is a dynamically typed programming language.",
      "description": "Python is a dynamically typed programming language designed by Guido Van Rossum. Much like the programming language Ruby, Python was designed to be easily read by programmers. Because of its large following and many libraries, Python can be implemented and used to do anything from webpages to scientific research.",
      "created_by": "Guido van Rossum",
      "released": "February 20, 1991",
      "created_at": "2016-12-07T00:07:02Z",
      "updated_at": "2017-10-27T22:45:43Z",
      "featured": true,
      "curated": true,
      "score": 111.92691
    },
    {
      "name": "jekyll",
      "display_name": "Jekyll",
      "short_description": "Jekyll is a simple, blog-aware static site generator.",
      "description": "Jekyll is a blog-aware, site generator written in Ruby. It takes raw text files, runs it through a renderer and produces a publishable static website.",
      "created_by": "Tom Preston-Werner",
      "released": "2008",
      "created_at": "2016-12-16T21:53:08Z",
      "updated_at": "2017-10-27T19:00:24Z",
      "featured": true,
      "curated": true,
      "score": 45.06729
    },
    {
      "name": "sass",
      "display_name": "Sass",
      "short_description": "Sass is a stable extension to classic CSS.",
      "description": "Sass is a stylesheet language with a main implementation in Ruby. It is an extension of CSS that makes improvements to the old stylesheet format, such as being able to declare variables and using a cleaner nesting syntax.",
      "created_by": "Hampton Catlin, Natalie Weizenbaum, Chris Eppstein",
      "released": "November 28, 2006",
      "created_at": "2016-12-16T21:53:45Z",
      "updated_at": "2018-01-16T16:30:40Z",
      "featured": true,
      "curated": true,
      "score": 42.455986
    },
    {
      "name": "homebrew",
      "display_name": "Homebrew",
      "short_description": "Homebrew is a package manager for macOS.",
      "description": "Homebrew is a package manager for Apple's macOS operating system. It simplifies the installation of software and is popular in the Ruby on Rails community.",
      "created_by": "Max Howell",
      "released": "2009",
      "created_at": "2016-12-17T20:30:44Z",
      "updated_at": "2018-02-06T16:14:56Z",
      "featured": true,
      "curated": true,
      "score": 19.194168
    }
  ]
}

Highlighting topic search results

You might want to highlight the matching search terms when displaying search results. The API offers additional metadata to support this use case. To get this metadata in your search results, specify the text-match media type in your Accept header. For example, via cURL, the above query would look like this:

curl -H 'Accept: application/vnd.github.v3.text-match+json, application/vnd.github.mercy-preview' \
'https://api.github.com/search/topics?q=ruby+is:featured'

This produces the same JSON payload as above, with an extra key called text_matches, which is an array of objects. These objects provide information such as the position of your search terms within the text, as well as the property that included the search term.

When searching for topics, you can get text match metadata for the topic's short_description, description, name, or display_name field. For details on the attributes present in the text_matches array, see text match metadata.

{
  "total_count": 6,
  "incomplete_results": false,
  "items": [
    {
      "name": "ruby",
      "display_name": "Ruby",
      "short_description": "Ruby is a scripting language designed for simplified object-oriented programming.",
      "description": "Ruby was developed by Yukihiro \"Matz\" Matsumoto in 1995 with the intent of having an easily readable programming language. It is integrated with the Rails framework to create dynamic web-applications. Ruby's syntax is similar to that of Perl and Python.",
      "created_by": "Yukihiro Matsumoto",
      "released": "December 21, 1995",
      "created_at": "2016-11-28T22:03:59Z",
      "updated_at": "2017-10-30T18:16:32Z",
      "featured": true,
      "curated": true,
      "score": 1750.5697,
      "text_matches": [
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:ruby",
          "object_type": "Topic",
          "property": "short_description",
          "fragment": "Ruby is a scripting language designed for simplified object-oriented programming.",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                0,
                4
              ]
            }
          ]
        },
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:ruby",
          "object_type": "Topic",
          "property": "description",
          "fragment": "Ruby was developed by Yukihiro \"Matz\" Matsumoto in 1995 with the intent of having an easily readable programming language. It is integrated with the Rails framework to create dynamic web-applications. Ruby's syntax is similar to that of Perl and Python.",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                0,
                4
              ]
            },
            {
              "text": "Ruby",
              "indices": [
                201,
                205
              ]
            }
          ]
        },
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:ruby",
          "object_type": "Topic",
          "property": "display_name",
          "fragment": "Ruby",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                0,
                4
              ]
            }
          ]
        },
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:ruby",
          "object_type": "Topic",
          "property": "name",
          "fragment": "ruby",
          "matches": [
            {
              "text": "ruby",
              "indices": [
                0,
                4
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "rails",
      "display_name": "Rails",
      "short_description": "Ruby on Rails (Rails) is a web application framework written in Ruby.",
      "description": "Ruby on Rails (Rails) is a web application framework written in Ruby. It is meant to help simplify the building of complex websites.",
      "created_by": "David Heinemeier Hansson",
      "released": "December 13 2005",
      "created_at": "2016-12-09T17:03:50Z",
      "updated_at": "2017-10-30T16:20:19Z",
      "featured": true,
      "curated": true,
      "score": 192.49652,
      "text_matches": [
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:rails",
          "object_type": "Topic",
          "property": "short_description",
          "fragment": "Ruby on Rails (Rails) is a web application framework written in Ruby.",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                0,
                4
              ]
            },
            {
              "text": "Ruby",
              "indices": [
                64,
                68
              ]
            }
          ]
        },
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:rails",
          "object_type": "Topic",
          "property": "description",
          "fragment": "Ruby on Rails (Rails) is a web application framework written in Ruby. It is meant to help simplify the building of complex websites.",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                0,
                4
              ]
            },
            {
              "text": "Ruby",
              "indices": [
                64,
                68
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "python",
      "display_name": "Python",
      "short_description": "Python is a dynamically typed programming language.",
      "description": "Python is a dynamically typed programming language designed by Guido Van Rossum. Much like the programming language Ruby, Python was designed to be easily read by programmers. Because of its large following and many libraries, Python can be implemented and used to do anything from webpages to scientific research.",
      "created_by": "Guido van Rossum",
      "released": "February 20, 1991",
      "created_at": "2016-12-07T00:07:02Z",
      "updated_at": "2017-10-27T22:45:43Z",
      "featured": true,
      "curated": true,
      "score": 112.94006,
      "text_matches": [
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:python",
          "object_type": "Topic",
          "property": "description",
          "fragment": "Python is a dynamically typed programming language designed by Guido Van Rossum. Much like the programming language Ruby, Python was designed to be easily read by programmers. Because of its large",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                116,
                120
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "jekyll",
      "display_name": "Jekyll",
      "short_description": "Jekyll is a simple, blog-aware static site generator.",
      "description": "Jekyll is a blog-aware, site generator written in Ruby. It takes raw text files, runs it through a renderer and produces a publishable static website.",
      "created_by": "Tom Preston-Werner",
      "released": "2008",
      "created_at": "2016-12-16T21:53:08Z",
      "updated_at": "2017-10-27T19:00:24Z",
      "featured": true,
      "curated": true,
      "score": 45.475624,
      "text_matches": [
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:jekyll",
          "object_type": "Topic",
          "property": "description",
          "fragment": "Jekyll is a blog-aware, site generator written in Ruby. It takes raw text files, runs it through a renderer and produces a publishable static website.",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                50,
                54
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "sass",
      "display_name": "Sass",
      "short_description": "Sass is a stable extension to classic CSS.",
      "description": "Sass is a stylesheet language with a main implementation in Ruby. It is an extension of CSS that makes improvements to the old stylesheet format, such as being able to declare variables and using a cleaner nesting syntax.",
      "created_by": "Hampton Catlin, Natalie Weizenbaum, Chris Eppstein",
      "released": "November 28, 2006",
      "created_at": "2016-12-16T21:53:45Z",
      "updated_at": "2018-01-16T16:30:40Z",
      "featured": true,
      "curated": true,
      "score": 42.83278,
      "text_matches": [
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:sass",
          "object_type": "Topic",
          "property": "description",
          "fragment": "Sass is a stylesheet language with a main implementation in Ruby. It is an extension of CSS that makes improvements to the old stylesheet format, such as being able to declare variables and using a cleaner nesting syntax.",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                60,
                64
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "homebrew",
      "display_name": "Homebrew",
      "short_description": "Homebrew is a package manager for macOS.",
      "description": "Homebrew is a package manager for Apple's macOS operating system. It simplifies the installation of software and is popular in the Ruby on Rails community.",
      "created_by": "Max Howell",
      "released": "2009",
      "created_at": "2016-12-17T20:30:44Z",
      "updated_at": "2018-02-06T16:14:56Z",
      "featured": true,
      "curated": true,
      "score": 19.368078,
      "text_matches": [
        {
          "object_url": "https://api.github.com/search/repositories?q=topic:homebrew",
          "object_type": "Topic",
          "property": "description",
          "fragment": "Homebrew is a package manager for Apple's macOS operating system. It simplifies the installation of software and is popular in the Ruby on Rails community.",
          "matches": [
            {
              "text": "Ruby",
              "indices": [
                131,
                135
              ]
            }
          ]
        }
      ]
    }
  ]
}

Search labels

Note: You can now use emoji in label names, add descriptions to labels, and search for labels in a repository. See the blog post for full details. To access these features and receive payloads with this data during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.symmetra-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Find labels in a repository with names or descriptions that match search keywords. Returns up to 100 results per page.

GET /search/labels

Parameters

Name Type Description
repository_id integer Required. The id of the repository.
q string Required. The search keywords.
sort string The sort field. Can be one of created or updated. Default: results are sorted by best match.
order string The sort order if the sort parameter is provided. Can be one of asc or desc. Default: desc

Example

Suppose you want to find labels in the linguist repository that match bug, defect, or enhancement. Your query might look like this:

curl -H 'Accept: application/vnd.github.symmetra-preview+json' \
'https://api.github.com/search/labels?repository_id=64778136&q=bug+defect+enhancement'

The labels that best match for the query appear first in the search results.

Status: 200 OK

{
  "total_count": 2,
  "incomplete_results": false,
  "items": [
    {
      "id": 418327088,
      "node_id": "MDU6TGFiZWw0MTgzMjcwODg=",
      "url": "https://api.github.com/repos/octocat/linguist/labels/enhancement",
      "name": "enhancement",
      "color": "84b6eb",
      "default": true,
      "description": "New feature or request.",
      "score": 0.1193385
    },
    {
      "id": 418327086,
      "node_id": "MDU6TGFiZWw0MTgzMjcwODY=",
      "url": "https://api.github.com/repos/octocat/linguist/labels/bug",
      "name": "bug",
      "color": "ee0701",
      "default": true,
      "description": "Something isn't working.",
      "score": 0.11928606
    }
  ]
}

Highlighting label search results

You might want to highlight the matching search terms when displaying search results. The API offers additional metadata to support this use case. To get this metadata in your search results, specify the text-match media type in your Accept header. For example, via cURL, the above query would look like this:

curl -H 'Accept: application/vnd.github.symmetra-preview+json, \
application/vnd.github.v3.text-match+json' \
'https://api.github.com/search/labels?repository_id=64778136&q=bug+defect+enhancement'

This produces the same JSON payload as above, with an extra key called text_matches, an array of objects. These objects provide information such as the position of your search terms within the text, as well as the property that included the search term.

When searching for labels, you can get text match metadata for the label name and description fields. For details on the attributes present in the text_matches array, see text match metadata.

{
  "total_count": 2,
  "incomplete_results": false,
  "items": [
    {
      "id": 418327088,
      "node_id": "MDU6TGFiZWw0MTgzMjcwODg=",
      "url": "https://api.github.com/repos/octocat/linguist/labels/enhancement",
      "name": "enhancement",
      "color": "84b6eb",
      "default": true,
      "description": "New feature or request.",
      "score": 0.119338505,
      "text_matches": [
        {
          "object_url": "https://api.github.com/repos/octocat/linguist/labels/enhancement",
          "object_type": "Label",
          "property": "name",
          "fragment": "enhancement",
          "matches": [
            {
              "text": "enhancement",
              "indices": [
                0,
                11
              ]
            }
          ]
        }
      ]
    },
    {
      "id": 418327086,
      "node_id": "MDU6TGFiZWw0MTgzMjcwODY=",
      "url": "https://api.github.com/repos/octocat/linguist/labels/bug",
      "name": "bug",
      "color": "ee0701",
      "default": true,
      "description": "Something isn't working.",
      "score": 0.119286075,
      "text_matches": [
        {
          "object_url": "https://api.github.com/repos/octocat/linguist/labels/bug",
          "object_type": "Label",
          "property": "name",
          "fragment": "bug",
          "matches": [
            {
              "text": "bug",
              "indices": [
                0,
                3
              ]
            }
          ]
        }
      ]
    }
  ]
}

Text match metadata

On github.com, we enjoy the context provided by code snippets and highlights in search results.

code-snippet-highlighting

API consumers have access to that information as well. Requests can opt to receive those text fragments in the response, and every fragment is accompanied by numeric offsets identifying the exact location of each matching search term.

To get this metadata in your search results, specify the text-match media type in your Accept header.

application/vnd.github.v3.text-match+json

The results will provide the same JSON payloads as shown above, with an extra key called text_matches. Inside the text_matches array, each object includes the following attributes:

Name Description
object_url The URL for the resource that contains a string property matching one of the search terms.
object_type The name for the type of resource that exists at the given object_url.
property The name of a property of the resource that exists at object_url. That property is a string that matches one of the search terms. (In the JSON returned from object_url, the full content for the fragment will be found in the property with this name.)
fragment A subset of the value of property. This is the text fragment that matches one or more of the search terms.
matches An array of one or more search terms that are present in fragment. The indices (i.e., "offsets") are relative to the fragment. (They are not relative to the full content of property.)

Example

Using cURL, and the example issue search above, our API request would look like this:

curl -H 'Accept: application/vnd.github.v3.text-match+json' \
'https://api.github.com/search/issues?q=windows+label:bug+language:python+state:open&sort=created&order=asc'

The response will include a text_matches array for each search result. In the JSON below, we have two objects in the text_matches array.

The first text match occurred in the body property of the issue. We see a fragment of text from the issue body. The search term (windows) appears twice within that fragment, and we have the indices for each occurrence.

The second text match occurred in the body property of one of the issue's comments. We have the URL for the issue comment. And of course, we see a fragment of text from the comment body. The search term (windows) appears once within that fragment.

{
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/215335/issues/132",
      "object_type": "Issue",
      "property": "body",
      "fragment": "comprehensive windows font I know of).\n\nIf we can find a commonly distributed windows font that supports them then no problem (we can use html font tags) but otherwise the '(21)' style is probably better.\n",
      "matches": [
        {
          "text": "windows",
          "indices": [
            14,
            21
          ]
        },
        {
          "text": "windows",
          "indices": [
            78,
            85
          ]
        }
      ]
    },
    {
      "object_url": "https://api.github.com/repositories/215335/issues/comments/25688",
      "object_type": "IssueComment",
      "property": "body",
      "fragment": " right after that are a bit broken IMHO :). I suppose we could have some hack that maxes out at whatever the font does...\n\nI'll check what the state of play is on Windows.\n",
      "matches": [
        {
          "text": "Windows",
          "indices": [
            163,
            170
          ]
        }
      ]
    }
  ]
}