| title | shortTitle | allowTitleToDifferFromFilename | intro | versions | topics | redirect_from | autogenerated | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
REST API endpoints for search |
Search |
true |
Use the REST API to search for specific items on {% data variables.product.product_name %}. |
|
|
|
rest |
You can use the REST API to search for the specific item you want to find. For example, you can find a user or a specific file in a repository. 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 {% data variables.product.product_name %} REST API provides up to 1,000 results for each search.
You can narrow your search using queries. To learn more about the search query syntax, see "AUTOTITLE."
Unless another sort option is provided as a query parameter, results are sorted by best match in descending order. Multiple factors are combined to boost the most relevant item to the top of the result list.
{% data reusables.enterprise.rate_limit %}
The REST API has a custom rate limit for searching. For authenticated requests, you can make up to 30 requests per minute{% ifversion fpt or ghec %} for all search endpoints except for the "Search code" endpoint. The "Search code" endpoint requires you to authenticate and limits you to 10 requests per minute{% endif %}. For unauthenticated requests, the rate limit allows you to make up to 10 requests per minute.
For information about how to determine your current rate limit status, see "Rate Limit."
Each endpoint for searching uses query parameters to perform searches on {% data variables.product.product_name %}. See the individual endpoints for examples that include the endpoint and query parameters.
A query can contain any combination of search qualifiers supported on {% data variables.product.product_name %}. The format of the search query is:
SEARCH_KEYWORD_1 SEARCH_KEYWORD_N QUALIFIER_1 QUALIFIER_N
For example, if you wanted to search for all repositories owned by defunkt that
contained the word GitHub and Octocat in the README file, you would use the
following query with the search repositories endpoint:
GitHub Octocat in:readme user:defunkt
Note: Be sure to use your language's preferred HTML-encoder to construct your query strings. For example:
// JavaScript
const queryString = 'q=' + encodeURIComponent('GitHub Octocat in:readme user:defunkt');See "AUTOTITLE" for a complete list of available qualifiers, their format, and an example of how to use them. For information about how to use operators to match specific quantities, dates, or to exclude results, see "AUTOTITLE."
You cannot use queries that:
- are longer than 256 characters (not including operators or qualifiers).
- have more than five
AND,OR, orNOToperators.
These search queries will return a "Validation failed" error message.
To keep the REST API fast for everyone, we limit the number of repositories a query will search through. The REST API will find up to 4,000 repositories that match your filters and return results from those repositories.
To keep the REST 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.
You need to successfully authenticate and have access to the repositories in your search queries, otherwise, you'll see a 422 Unprocessable Entry error with a "Validation Failed" message. For example, your search will fail if your query includes repo:, user:, or org: qualifiers that request resources that you don't have access to when you sign in on {% data variables.product.prodname_dotcom %}.
When your search query requests multiple resources, the response will only contain the resources that you have access to and will not provide an error message listing the resources that were not returned.
For example, if your search query searches for the octocat/test and codertocat/test repositories, but you only have access to octocat/test, your response will show search results for octocat/test and nothing for codertocat/test. This behavior mimics how search works on {% data variables.product.prodname_dotcom %}.
On {% data variables.product.prodname_dotcom %}, you can use the context provided by code snippets and highlights in search results. The endpoints for searching return additional metadata that allows you to highlight the matching search terms when displaying search results.
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.text-match+jsonWhen you provide the text-match media type, you will receive an extra key in the JSON payload called text_matches that provides information about the position of your search terms within the text and the property that includes the search term. 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.) |
Using a curl command, and the example issue search above, our API
request would look like this:
curl -H 'Accept: application/vnd.github.text-match+json' \
'{% data variables.product.rest_url %}/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
]
}
]
}
]
}