Skip to content
This repository has been archived by the owner on Nov 1, 2017. It is now read-only.

Latest commit

 

History

History
442 lines (332 loc) · 24.3 KB

search.md

File metadata and controls

442 lines (332 loc) · 24.3 KB
Raw
title
Search

Search

{:toc}

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 {{ site.data.variables.product.product_name }} 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.

{% if page.version == 'dotcom' %}

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.

{% endif %}

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 as described by the in-browser repository search documentation and search syntax documentation:

  • 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.
  • size Finds repositories that match a certain size (in kilobytes).
  • forks Filters repositories based on the number of forks.
  • fork Filters whether forked repositories should be included (true) or only forked repositories should be returned (only).
  • created or pushed Filters repositories based on date of creation, or when they were last updated.
  • user or repo Limits searches to a specific user or repository.
  • language Searches repositories based on the language they're written in.
  • stars Searches repositories based on the number of stars.

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.

<%= headers 200, {:pagination => default_pagination_rels{% if page.version == 'dotcom' %}, 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:repo_search_v3_results) %>

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:

<%= json(:repo_search_v3_results_highlighting) %>

Search code

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

GET /search/code

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 {% if page.version != 'dotcom' and page.version >= 2.2 %} 10 MB {% else %} 384 KB {% endif %} are searchable.
    • {% if page.version == 'dotcom' %}
  • 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.
    • {% endif %}

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 {{ site.data.variables.product.product_name }} 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:

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.

<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:code_search_v3_results) %>

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:

<%= json(:code_search_v3_results_highlighting) %>

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

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.

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.

<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:issue_search_v3_results) %>

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:

<%= json(:issue_search_v3_results_highlighting) %>

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

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.

<%= headers 200, {:pagination => default_pagination_rels,{% if page.version == 'dotcom' %} 'X-RateLimit-Limit' => 20, 'X-RateLimit-Remaining' => 19{% endif %}} %> <%= json(:user_search_v3_results) %>

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.)

<%= json(:user_search_v3_results_highlighting) %>

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.

<%= json(:issue_search_v3_results_highlighting) %>