Search

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 a 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 20 requests per minute. For unauthenticated requests, the rate limit allows you to make up to 5 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

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

GET /search/repositories

Parameters

Name Type Description
q string 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:

Example

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

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

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
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19
{
  "total_count": 40,
  "incomplete_results": false,
  "items": [
    {
      "id": 3081286,
      "name": "Tetris",
      "full_name": "dtrupenn/Tetris",
      "owner": {
        "login": "dtrupenn",
        "id": 872147,
        "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": "e7956084e75f239de85d3a31bc172ace",
        "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

Some API consumers will 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. (See the section on text match metadata for full details.)

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 code

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

GET /search/code

Parameters

Name Type Description
q string 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:

Example

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

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
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,
        "name": "jquery",
        "full_name": "jquery/jquery",
        "owner": {
          "login": "jquery",
          "id": 70142,
          "avatar_url": "https://0.gravatar.com/avatar/6906f317a4733f4379b06c32229ef02f?d=https%3A%2F%2Fidenticons.github.com%2Ff426f04f2f9813718fb806b30e0093de.png",
          "gravatar_id": "6906f317a4733f4379b06c32229ef02f",
          "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

Some API consumers will 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. (See the section on text match metadata for full details.)

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

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

GET /search/issues

Parameters

Name Type Description
q string 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:

Example

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

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
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",
      "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,
      "number": 132,
      "title": "Line Number Indexes Beyond 20 Not Displayed",
      "user": {
        "login": "Nick3C",
        "id": 90254,
        "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": "934442aadfe3b2f4630510de416c5718",
        "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": [
        {
          "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

Some API consumers will 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. (See the section on text match metadata for full details.)

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 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:

Example

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

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
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19
{
  "total_count": 12,
  "incomplete_results": false,
  "items": [
    {
      "login": "mojombo",
      "id": 1,
      "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": "25c7c18223fb42a4c6ae1c8db6f50f9b",
      "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

Some API consumers will 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. (See the section on text match metadata for full details.)

{
  "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
          ]
        }
      ]
    }
  ]
}

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 hash 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
          ]
        }
      ]
    }
  ]
}