Improvements to the Search API

Today we’re shipping two improvements to the new Search API.

More Text Match Metadata

When searching for code, the API previously provided text match metadata (i.e., “highlights”) for file content. Now, you can also get this metadata for matches that occur within the file path.

For example, when searching for files that have “client” in their path, the results include this match for lib/octokit/client/commits.rb:

{
  "name": "commits.rb",
  "path": "lib/octokit/client/commits.rb",
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/417862/contents/lib/octokit/client/commits.rb?ref=8d487ab06ccef463aa9f5412a56f1a2f1fa4dc88",
      "object_type": "FileContent",
      "property": "path",
      "fragment": "lib/octokit/client/commits.rb",
      "matches": [
        {
          "text": "client",
          "indices": [ 12, 18 ]
        }
      ]
    }
  ]
  // ...
}

Better Text Match Metadata

Before today, the API applied HTML entity encoding to all fragment data. For example, imagine your search returns an issue like rails/rails#11889:

The response would include a text_matches array with the following object:

{
  "fragment": "undefined method `except' for #<Array:XXX>",
  // ...
}

Inside the fragment value, we see HTML-encoded entities (e.g., <). Since we’re returning JSON (not HTML), API clients might not expect any HTML-encoded text. As of today, the API returns these fragments without this extraneous encoding.

{
  "fragment": "undefined method `except' for #<Array:XXX>",
  // ...
}

Preview Period

We’re about halfway through the preview period for the new Search API. We appreciate everyone that has provided feedback so far. Please keep it coming!