api/search

The Search API finds verses containing words or phrases and returns both an ordered match list and chapter-grouped Scripture. It applies matching rules derived from the writing system of the text, so applications can send an ordinary search string without implementing their own language detector.

Choose a data version#

Version	Base route	Guide
v2	https://search.getbible.net/v2/{translation}/{search}	Search v2
v3	https://search.getbible.net/v3/{translation}/{search}	Search v3

The HTTP filters and result envelope are the same. The selected data version controls the source verses: v3 can retain lexical tokens, annotation spans and paragraph-start metadata. Chapter-level editorial layout is obtained from the static Bible API.

Search in one request#

curl --fail-with-body --compressed --get \
  'https://search.getbible.net/v3/kjv' \
  --data-urlencode 'q=faith hope' \
  --data-urlencode 'scope=new_testament' \
  --data-urlencode 'limit=25'

By default, every search unit must occur in the verse, matching is case-insensitive, applicable diacritics are folded and results are in canonical order. The full version guides document every filter, accepted type, limit and error.

GET and POST use the same search#

GET accepts URL parameters. POST accepts the same parameters, a JSON object, or both. A value supplied in the path wins over the query string, which wins over the body, which wins over configured defaults. Explicit false and 0 are values; JSON null leaves a lower-priority/default value unchanged.

curl --fail-with-body --compressed \
  --header 'Content-Type: application/json' \
  --data '{"translation":"kjv","q":"faith hope","words":"all","sort":"relevance","limit":25}' \
  'https://search.getbible.net/v3'

Use GET for shareable, cacheable searches and POST when a structured body is more convenient. POST search responses are not cached. Neither method writes or modifies Scripture.

One envelope, two kinds of result#

Member	Contents
query	Search text, kind, translation, engine version and counts; full-text searches also include criteria, pagination, source hash, cache state, analysis and cost
results	Scripture grouped by {translation}_{book}_{chapter}
matches	Ordered verse identities; full-text matches also include score, occurrences and matched terms

Check query.kind. A string that resolves as a Scripture reference returns kind: "reference"; it does not apply full-text filtering or pagination. Full-text results use kind: "search". For relevance sorting, matches is the authoritative order; do not use the property order of chapter objects as the ranking.

Matching across scripts#

The librarian inspects Unicode script properties in both the query and corpus. Alphabetic scripts use word units; continuous scripts such as Han and Hangul use positional character units; abjad handling supports optional vowel-point folding and attached-particle stems. Brahmic scripts preserve vowel-bearing combining marks. Mixed-script input is handled by its individual runs rather than switching the entire string to substring matching. Original returned verse text remains unchanged. See the librarian search documentation.

Pagination and limits#

The public HTTP contract accepts limit from 1 to 100 and offset from 0 to 10000. Use query.has_more and advance the offset by the number returned. Keep the query, translation, API version and criteria unchanged while paging. If the source hash changes between pages, restart to avoid combining different data generations.

The Python librarian's local limits can differ from the public HTTP service. Use the API's OpenAPI limits when integrating over HTTP. A partner bearer token exempts public rate budgets; it does not disable search cost, input or execution limits.

Access and operational behavior#

Public calls work without a token under per-address budgets. Request application access through support or [email protected], naming search.getbible.net among the domains needed. Send the issued token in the Authorization header.

Retry 429 and temporary 503 responses according to Retry-After. Narrow a repeatedly expensive request with a scope, book filter or more precise words. A first request for an uncached translation can include corpus preparation time. Handle timeouts without assuming that the translation does not exist.

Contracts and upstream documentation#

Resource	Link
Service overview	search.getbible.net
Version discovery	versions.json
v2 documentation and OpenAPI	Documentation · OpenAPI JSON
v3 documentation and OpenAPI	Documentation · OpenAPI JSON
Matching and search fields	Librarian search
Runtime contract	Runtime endpoints
Source data and study metadata	Bible v3

Use the central GetBible support desk for help with search behavior or an integration.