TermSearch

Endpoint: /api/v2/termSearch

Parameters

There are two kinds of parameters. The main parameter is the search term, but a number of additional options may be specified.

Search Terms

Search terms are specified using "friendly" conversions of term objects in the "t" namespace. "t" stands for searchTerm, but is abbreviated because of the verbosity of this part of the query. A helper library for these conversions may be found here. A SearchTerm object is specified as:

type SearchAttributeObject = {
    [key: string keyof attributes]: string
}

type SearchTerm = {
    inverted: boolean
    data: SearchAttributeObject
}

Here is an example of the conversion from search terms to a GET parameters. Consider the following array of search terms:

const searchTerms: SearchTerm[] = [{
    inverted: true,
    data: { 
        "lexeme": "אֱלֹהִים"
    }
},{
    inverted: false,
    data: {
        "lexeme": "דבר",  //i.e., lexeme = דבר
        "stem": "piel"  // i.e., verbal stem = hiphil
    }
}]

The searchTerms array contains two SearchTerm objects. When inverted is false, there is no need to include it when querying Parabible. A pretty-printed friendly serialization of this object for the searchTerm parameter is:

t.0.inverted=true&
t.0.data.lexeme=אֱלֹהִים&
t.1.data.lexeme=דבר&
t.1.data.stem=piel

Note: The Parabible client represents the data property of search terms as an array of key/value pairs rather than a SearchAttributeObject and converts them to this format when querying the server. The API is set up this way to make queries minimally verbose.

Search Options

Parameter	Description
modules	A case insensitive, comma separated list of module abbreviations. Any module that has text in a parallel ID that contains a match will be included in results. The SearchTerms endpoint will search all modules for SearchTerms irrespective of whether they are included in this parameter.
treeNodeType	The type of syntax range within which search terms must appear. Accepts phrase, clause, sentence, and verse, all of which require that the search terms all appear in the same module. Additionally, parallel may be specified, which allows search terms to appear in any module, provided that they are appear in aligned verses.
reference	[Optional] Comma separated list of reference strings. The SearchTerms endpoint will filter results to those ocurring within specified reference(s).
pageSize	[Optional] Size of page (i.e., number of results) to return. Default: 10. Maximum: (TODO: define max).
pageNumber	[Optional] Page number to return. Default: 0. (TODO: specify what happens when pagenumber is out of bounds).

Example: /api/v2/termSearch?t.0.inverted=true&t.0.data.lexeme=אֱלֹהִים&t.1.data.lexeme=דבר&t.1.data.stem=piel&modules=net,etcbc+bhsa&treeNodeType=parallel&pageNumber=0&pageSize=10

Returns

Types for the /termSearch endpoint return are:

// Some matches span more than one verse and, therefore, each match has an array of ordered parallel IDs.
type ParallelIdMatch = number[]

// type MatchingText ⇒ see [/text]

type MatchingWord = {
    wid: number
    moduleId: number
}

type WarmWordSet = {
    moduleId: number
    wids: number[]
}

type TextResult = {
	parallelId: number
	moduleId: number
	rid: number
	type: "wordArray" | "html"
	wordArray: WordArray
	html: string
}

type TermSearchEndpointResult = {
    count: number
    matchingText: TextResult[][][]
    matchingWords: MatchingWord[]
    warmWords: WarmWordSet[]
}

To display results, map over the matchingText array. The first dimension represents rows of results; the second represents each module in the request (in the order requested); the third dimension reperesents the TextResult objects (it is an array because, for some verseNodeTypes [ahem "sentence"], the result may span more than one verse).