Query For Document Matches

This example shows you how to query your trusted data sources for relevant snippets

Querying for document snippets in your trusted document library

Locusive's API acts as an alternative to a vector database, letting you query (and add) documents to your account. By querying your documents, you can get the most relevant paragraphs, snippets, and rows (if you've indexed a spreadsheet) for your query, which can be useful for making contextual requests for a large language model.

The Query For Document Matches API endpoint allows you to specify a query and get back a list of the most relevant results.


POST <https://api.locusive.com/v1/documents/top_snippets>

Request Headers

The API request must include the following header:

Authorization: Bearer <Your-Secret-Key> - The secret key for authenticating the API request.

Request Body Parameters

  • query (string, required): The query that you want to use to find matches
  • maxResults (integer): The maximum number of results to retrieve
  • minimumSimilarityScore (float): A number between 0 and 1 that represents how similar your matches must be to your query, 0 being no similarity and 1 being exact similarity
  • documentIds (array of strings): The IDs of documents that must be used to service the query
  • documentNames (array of strings): The names of the documents that must be used to service the query

Example Java code

package com.locusive.public_api.ad_hoc;

import com.google.gson.Gson;
import com.locusive.public_api.PublicApiConfig;
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import java.util.HashMap;
import java.util.Map;

public class AdHocPublicApiQuerier {
	private static final String ApiKey = "your-key-here";
	private static final String Url = "https://api.locusive.com/v1/documents/top_snippets";

	public static void main(String[] args) {
		try {
			HttpPost httpPost = new HttpPost(Url);
			httpPost.addHeader("Authorization", "Bearer " + ApiKey);
			httpPost.addHeader("Content-Type", "application/json");

			// Construct the request body
			Map<String, Object> requestBody = new HashMap<>();
			requestBody.put("query", "Where is Antarctica?");
			requestBody.put("minimumSimilarityScore", 0.7f);
			requestBody.put("maxResults", 100);

			String jsonBody = new Gson().toJson(requestBody);
			httpPost.setEntity(new StringEntity(jsonBody));

			// Execute the HTTP request
			try (CloseableHttpClient httpClient = HttpClients.createDefault();
			     CloseableHttpResponse response = httpClient.execute(httpPost)) {

				HttpEntity entity = response.getEntity();
				if (entity != null) {
					String result = EntityUtils.toString(entity);
		} catch (Exception ex) {


  • 200: A list of results
  • 400: A bad request error
  • 500: If there is an internal server error while processing the request

Example Response

    "parentDocumentName": "Antarctica - Wikipedia",
    "parentDocumentUri": "https://en.wikipedia.org/wiki/Antarctica",
    "parentDocumentType": "Web page",
    "text": "used phrases such as \"the Antarctic \r\nContinent\". They searched for a more poetic replacement, suggesting names \r\nsuch as Ultima and Antipodea.[10] Antarctica was adopted in the 1890s, with \r\nthe first use of the name being attributed to the Scottish cartographer \r\nJohn George Bartholomew.[11]\r\n\r\n\r\nGeography\r\n\r\nMain article: Geography of Antarctica\r\nSee also: Extreme points of Antarctica and List of mountains in Antarctica\r\n[map of Antarctica] Eastern Antarctica is to the right of the \r\nTransantarctic Mountains and Western Antarctica is to the left.\r\n\r\nPositioned asymmetrically around the South Pole and largely south of the \r\nAntarctic Circle (one of the five major circles of latitude that mark maps \r\nof the world), Antarctica is surrounded by the Southern Ocean.[note 2] \r\nRivers exist in Antarctica, the longest is the Onyx. Antarctica covers more \r\nthan 14.2 million km2 (5,500,000 sq mi), making it the fifth-largest \r\ncontinent, slightly less than 1.5 times the area of the United States. Its \r\ncoastline is almost 18,000 km (11,200 mi) long:[1] as of 1983[update], of \r\nthe four coastal types, 44% of the coast is floating ice in the form of an \r\nice shelf, 38% consists of ice walls that rest on rock, 13% is ice streams \r\nor the edge of glaciers, and the remaining 5% is exposed rock.[13]\r\n\r\nThe lakes that lie at the base of the continental ice sheet occur mainly in \r\nthe McMurdo Dry Valleys or various oases.[14] Lake Vostok, discovered \r\nbeneath Russia\u0027s Vostok Station, is the largest subglacial lake globally \r\nand one of the largest lakes in the world. It was once believed that the \r\nlake had been sealed off for millions of years, but scientists now estimate \r\nits water is replaced by the slow melting and freezing of ice caps every \r\n13,000 years.[15] During the summer, the ice at the edges of the lakes can \r\nmelt, and liquid moats temporarily form. Antarctica has both saline and \r\nfreshwater lakes.[14]\r\n\r\nAntarctica is divided into West Antarctica and East Antarctica by the \r\nTransantarctic Mountains, which stretch from Victoria Land to the Ross Sea\r\n.[16][17] The vast majority of Antarctica is covered by the Antarctic ice \r\nsheet, which averages 1.9 km (1.2 mi) in thickness.[18] The ice sheet \r\nextends to all but a few oases, which, with the exception of the McMurdo \r\nDry Valleys, are located in coastal areas.[19] Several Antarctic ice \r\nstreams flow to one of the many Antarctic ice shelves, a process described \r\nby ice-sheet dynamics.[20]\r\n\r\n[photograph of Vinson Massif] Vinson Massif from the northwest, the highest \r\npeak in Antarctica\r\n\r\nEast Antarctica comprises Coats Land, Queen Maud Land, Enderby Land, Mac. \r\nRobertson Land, Wilkes Land, and Victoria Land. All but a small portion of \r\nthe region lies within the Eastern Hemisphere. East Antarctica is largely \r\ncovered by the East Antarctic Ice Sheet.[21] There are numerous islands \r\nsurrounding Antarctica, most of which are volcanic and very young by \r\ngeological standards.[22] The most prominent exceptions to this are the \r\nislands of the Kerguelen Plateau, the earliest of which formed around 40 \r\nMa.[22][23]\r\n\r\nVinson Massif, in the Ellsworth Mountains, is the highest peak in \r\nAntarctica at 4,892 m (16,050 ft).[24] Mount Erebus on Ross ",
    "description":"Antarctica is the fifth-largest continent, surrounded by the Southern Ocean, and divided into West and East Antarctica by the Transantarctic Mountains, with the majority of the continent covered by the Antarctic ice sheet.",
    "parentDocumentName": "Antarctica - Wikipedia",
    "parentDocumentUri": "https://en.wikipedia.org/wiki/Antarctica",
    "parentDocumentType": "Web page",
    "text": "recorded in Antarctica near the Beardmore Glacier by Frank \r\nWild on the Nimrod Expedition in 1907, and low-grade coal is known to exist \r\nacross many parts of the Transantarctic Mountains.[65] The Prince Charles \r\nMountains contain deposits of iron ore.[66] There are oil and natural gas \r\nfields in the Ross Sea.[67]\r\n\r\n\r\nClimate\r\n\r\nMain article: Climate of Antarctica\r\n[photograph of blue ice]\r\nBlue ice covering Lake Fryxell, in the Transantarctic Mountains\r\n[Two men looking at a penguin on a sunny day]\r\nTemperate conditions near the coast in December\r\n\r\nAntarctica is the coldest, windiest, and driest of Earth\u0027s continents.[1] \r\nThe lowest natural air temperature ever recorded on Earth was −89.2 °C \r\n(−128.6 °F) at the Russian Vostok Station in Antarctica on 21 July 1983.\r\n[68] A lower air temperature of −94.7 °C (−138.5 °F) was recorded in 2010 \r\nby satellite—however, it may have been influenced by ground temperatures \r\nand was not recorded at a height of 2 m (7 ft) above the surface as \r\nrequired for official air temperature records.[69] Average temperatures can \r\nreach a minimum of between −80 °C (−112 °F) in the interior of the \r\ncontinent during winter and a maximum of over 10 °C (50 °F) near the coast \r\nin summer.[70]\r\n\r\nAntarctica is a polar desert with little precipitation; the continent \r\nreceives an average equivalent to about 150 mm (6 in) of water per year, \r\nmostly in the form of snow. The interior is dryer and receives less than 50 \r\nmm (2 in) per year, whereas the coastal regions typically receive more than \r\n200 mm (8 in).[71] In a few blue-ice areas, the wind and sublimation \r\nremove more snow than is accumulated by precipitation.[72] In the dry \r\nvalleys, the same effect occurs over a rock base, leading to a barren and \r\ndesiccated landscape.[73] Antarctica is colder than the Arctic region, as \r\nmuch of Antarctica is over 3,000 m (9,800 ft) above sea level, where air \r\ntemperatures are colder. The relative warmth of the Arctic Ocean is \r\ntransferred through the Arctic sea ice and moderates temperatures in the \r\nArctic region.[74]\r\n\r\n\r\nRegional differences\r\n\r\nEast Antarctica is colder than its western counterpart because of its \r\nhigher elevation. Weather fronts rarely penetrate far into the continent, \r\nleaving the centre cold and dry, with moderate wind speeds. Heavy snowfalls \r\nare common on the coastal portion of Antarctica, where snowfalls of up to \r\n1.22 m (48 in) in 48 hours have been recorded. At the continent\u0027s edge, \r\nstrong katabatic winds off of the polar plateau often blow at storm force. \r\nDuring the summer, more solar radiation reaches the surface at the South \r\nPole than at the equator because of the 24 hours of sunlight received there \r\neach day.[1]\r\n\r\n\r\nClimate change\r\n\r\nMain article: Climate change in Antarctica\r\n[Warming in West Antarctica was up to 0.25 degrees Celsius, whereas East \r\nAntarctica saw a more minor temperature rise]\r\nThe warming trend for Antarctica from 1957 to 2006, based on the analysis \r\nof weather station and satellite data; dark tints over West Antarctica \r\nindicate that the region warmed most per decade.\r\n[Legend]\r\n\r\nOver the second half of the 20th century, the Antarctic ",
    "description":"Antarctica has various natural resources such as coal, iron ore, oil, and natural gas, and has extreme climate conditions with very low temperatures and little precipitation, making it the coldest, windiest, and driest continent on Earth. There are regional differences in climate, with East Antarctica being colder than the west, and the continent is experiencing the effects of climate change with rising temperatures.",

What’s Next