Implement Type-Ahead Autocomplete Search with Hexagraph

Power type-ahead search in your app using Hexagraph’s autocomplete endpoint, which surfaces works, authors, sources, institutions, publishers, and funders.

The /autocomplete endpoint provides fast, type-ahead search suggestions across all Hexagraph entity types, making it ideal for building search interfaces in your application. As the user types, you can feed each keystroke to this endpoint and render a live dropdown of matching scholarly entities — works, researchers, journals, institutions, publishers, and funders — without running a full paginated search.

General Autocomplete

GET /autocomplete?q=<query> returns suggestions across every entity type in a single call. Use this when you want a unified search box that surfaces any kind of scholarly entity.

curl "https://hexagraph-core.onrender.com/autocomplete?q=machine+learning"

Example response

[
  {
    "id": "OA:W2107277218",
    "display_name": "Machine Learning for Natural Language Processing",
    "entity_type": "output",
    "hint": "2022 · Journal of Artificial Intelligence Research"
  },
  {
    "id": "OA:A3109847201",
    "display_name": "Yann LeCun",
    "entity_type": "author",
    "hint": "New York University · 142,893 citations"
  },
  {
    "id": "OA:S2041851",
    "display_name": "Machine Learning",
    "entity_type": "source",
    "hint": "Springer · ISSN 0885-6125"
  },
  {
    "id": "OA:I136199984",
    "display_name": "MIT Computer Science and Artificial Intelligence Laboratory",
    "entity_type": "institution",
    "hint": "Massachusetts Institute of Technology"
  }
]

Results are sorted by relevance across all entity types. The entity_type field tells your UI which icon or label to render alongside each suggestion.

Entity-Specific Autocomplete

GET /autocomplete/{entity}?q=<query> restricts suggestions to a single entity type. Use this when your search context is already known — for example, an “Add Author” field in a paper submission form should only surface author suggestions.

Supported entity values

Entity	Description
outputs	Scholarly works (journal articles, preprints, books)
authors	Researcher profiles
sources	Journals, repositories, and other publication venues
institutions	Universities, research labs, and other organisations
publishers	Publishing companies and organisations
funders	Grant-making bodies and funding agencies

curl "https://hexagraph-core.onrender.com/autocomplete/authors?q=einstein"

Example response

[
  {
    "id": "OA:A2048391207",
    "display_name": "Albert Einstein",
    "entity_type": "author",
    "hint": "Institute for Advanced Study · 89,402 citations"
  },
  {
    "id": "OA:A3301847501",
    "display_name": "Albert Einstein College of Medicine Faculty",
    "entity_type": "author",
    "hint": "Albert Einstein College of Medicine · 1,204 citations"
  }
]

By scoping the request to /autocomplete/authors, only author records are returned — no outputs, sources, or institutions will appear in the list, keeping dropdown results clean and contextually appropriate.

Integration Example

Below is a minimal JavaScript implementation of a debounced type-ahead search using the general autocomplete endpoint. The 300 ms debounce prevents excessive requests while the user is still typing.

let debounceTimer;

async function searchEntities(query) {
  const res = await fetch(
    `https://hexagraph-core.onrender.com/autocomplete?q=${encodeURIComponent(query)}`
  );
  return res.json();
}

function onSearchInput(event) {
  const query = event.target.value.trim();

  // Don't fire for very short inputs
  if (query.length < 2) return;

  // Debounce: wait 300ms after the user stops typing
  clearTimeout(debounceTimer);
  debounceTimer = setTimeout(async () => {
    const suggestions = await searchEntities(query);
    renderSuggestions(suggestions);
  }, 300);
}

function renderSuggestions(suggestions) {
  const list = document.getElementById("suggestions");
  list.innerHTML = suggestions
    .map(
      (s) => `<li data-id="${s.id}" data-type="${s.entity_type}">
                <strong>${s.display_name}</strong>
                <span class="hint">${s.hint}</span>
              </li>`
    )
    .join("");
}

document.getElementById("search-input").addEventListener("input", onSearchInput);

To scope the search to a specific entity type, replace the autocomplete path segment:

`https://hexagraph-core.onrender.com/autocomplete/authors?q=${encodeURIComponent(query)}`

Response Fields

Each object in the suggestions array contains the following fields:

Field	Type	Description
id	string	The entity’s Hexagraph OA:ID (e.g. OA:W…, OA:A…, OA:S…)
display_name	string	Human-readable name suitable for rendering in a dropdown
entity_type	string	One of output, author, source, institution, publisher, funder
hint	string	A short contextual string (e.g. year and venue for outputs, citation count for authors) to help users distinguish between similar results

Use id to make a follow-up lookup to the appropriate detail endpoint (/outputs/{id}, /authors/{id}, etc.) once the user selects a suggestion.

Autocomplete queries count against your rate limit just like any other request (30 requests/min, 1,000/day). For type-ahead interfaces, debounce requests so you send at most one query per 300 ms — this keeps a fast typist from consuming dozens of quota slots per second and ensures a smoother user experience overall.