An easy way of integrating to STEP is to use the browser to render STEP and simply integrate with the URL. These URLs control a number of different parameters, ranging from Bible references, version and commentaries, display options, search terms, ... The following page attempts to describe the different parts of the URL.

The STEP URL defined

The following fragment is taken directly from the online version and illustrate the different parts of the URL:

http://www.stepbible.org/?q=version=ESV|version=NIV|strong=G0018|reference=Matt&options=VLGUVN&display=INTERLEAVED

It can be split up in different fragments:

URL fragment	Field name (used in the rest of this document	Description
http://www.stepbible.org/	Base URL	This is the base URL to which STEP will call out to. For Desktop editions of the software, this will usually be http://localhost:8989/. Our development site is at http://dev.stepbible.org
q=version=ESV\|version=NIV\|strong=G0018\|reference=Matt	Search query	The query that STEP attempts to parse. This describes the action that user has committed to. Visually, this is the textual representation of the different roundels in the search box: This could be a Bible passage lookup, a word search against the original text, a search by meaning, etc. The query can be split up in different parts, each part being a search term. The search terms are separated by a pipe delimiter (\|) and STEP copes with the delimiter whether it is URL encoded or passed as is. Some browsers may complain about the lack of URL encoding (though none have been encountered so far). Each search term takes the form of: type=data Type is the type of data that is being requested. This qualifies the data. This is usually done by the user selecting an option from a dropdown. At the time of selection from the dropdown, STEP can determine that by selecting the word 'hesed', the user is wanting to look up data H2618. As a result, on clicking search, the term strong=H2618 is added to the URL. The list of data types is explained below .
options=VLGUVN	Display options	Depending on the type of search requested by the user and the chosen modules (Bibles and commentaries), different options are made available. For example, displaying verses line by line is always available for any Bible/commentary. However, cross-references may only be available in certain Bibles. Other times, the view of the data itself doesn't support those options (e.g. turning Greek accents off is not supported in English texts). A full list of options is described below.
display=INTERLEAVED	Display mode	There are 6 different mods of display. A display mode affects the structure and layout of the text. For example, a user may opt to display multiple versions and compare their textual differences, or see them in column. The full list of display options is described below.
qFilter=H0023,H0054	Search filter	A comma separated list of strong numbers (or left out to not apply a filter)
sort=false (sort=VOCABULARY)	Sort type	Sometimes, search results can be aggregated by strong number (VOCABULARY) or by scripture reference (false). This means the user sees the same set of verses, however STEP will insert headings for group of verses that belong to the same strong number.

The power of STEP comes by the joining of multiple search terms together to combine searches, references, Bibles and commentaries. This allows the user to create complicated searches. For example, a user could cast a wide net over all subjects referring to David and refine it to only those passages that contain the text word 'David'. This means that although a passage may be missing the actual word David, the user ends up seeing all passages that refer to the throne of David, and not that of any other kind.

Search query

The most complicated part of this document is this next section - so please keep reading!

Data types

The following types exist:

	Examples	Description
version	version=ESV version=Luther	Identifies a particular resource (a version of the Bible, or a commentary)
reference	reference=Mark.2-reference=Mark.3 reference=Mark.2:10 reference=Mark%202 (URL encoded) reference=Mwa 2 (Swahili names) reference=Mar.2:10-ff (verse 10 to end of chapter)	Identifies a reference, e.g. Gen.1.1. References are to lookup a passage or to limit the scope of a search. STEP attempts to parse any reference as best it can. For example, STEP is able to parse Swahili references, etc. The best way of working out what is supported is to try them out. STEP itself attempts to ensure there URL always contains a well-formed OSIS reference (e.g. Book.chap.num-Book.chap.num, Book.chap, etc.) This is so that sharing URLs on the internet, does not rely on the browser's language. (Note: on the desktop, the language will be detected from the browser, which is usually the OS language)
text	text=Abraham text=Melkizedc~ (allow for spelling alternatives) text=Abra* (and much much more)	Carries out a text search. A text search is defined as a search for the specified term in the selected resources. If the selected resource(s) are Greek, then it attempts to match the term (assumed to be input in Greek) to the selected corpus. If the resource is in English, the term is assumed to be in English, etc. etc. e.g. imagine opening up a Word document, and pressing CTRL+F and keying in a term. Text searches are however much more powerful in that they support many different types of operators. Please see Query Syntax for extensive detail (row marked as search prefix 't='
syntax	syntax=og=agathos syntax=og=agathos~ sh=throne (and much much more)	Useful in many different cases to obtain more fine grained control of the types of searches run. Please see Query Syntax for extensive detail on the syntax. As an example, if a strong number isn't available for example, then syntax=og=agathos will lookup the Greek word agathos against STEP's lexicon. This will return a number of strong numbers which will in turn me used to search. This syntax offers numerous types of searches!
strong	strong=H0001 (search for the word 'father')	A search by strong number. This search is used mainly when using the search dropdown. Selecting an entry from the search dropdown effectively searches the strong number. The syntax search described above allows more flexible 'original word searches' . The search by strong is effectively shortcuting a number of lookups and is therefore fractionally faster.
meanings	meanings=throne	Searches for all words that mean a particular term in English. The search effectively looks up various fields in all entries in the STEP lexicon. The strong numbers of any matching entries are collected and then used to query the selected resources.
subject	subject=throne	Searches all headings contained in the selected resources for a particular search term and displays the headings matched. The ESV and NIV are always added to the resources included in the search, though the search results will prefer headings that have been found in the Bibles&Commentaries specifically selected by the user.
nave	nave=throne	Searches the top-level headings of the Nave topical "concordance" and returns all verses that are found under the top-level heading. The results are grouped under their nave headings
xnave	xnave=throne	Similar to nave=, but searches across all headings contained in the Nave topical concordance.
topicref	topicref=Gen.1	Searches for all verses that are related by subject. The search effectively carries out the following steps: Get the reference Work out which themes are attached to that reference (e.g. by looking at the Nave topical concordance) Find all verses that also have these same themes Return these verses to the user in their selected resources The search was originally built to support a single verse, however it is extended and optimized to also be used for chapters and whole books.
relatedrefs	relatedrefs=Gen.1.1	Find related verses. Related verses are defined as verses that share a certain commonality in the originally. The following steps are taken: Get the reference Look up from the Hebrew/Greek/ESV text the strong numbers contained in the verse Remove any strong number that occurs more than 200 times (these words are currently deemed insignificant as they occur too often) Search for verses that share at least 2 strong numbers. Verses are scored and the top 50 results are currently returned to the users. Return the verses to the user All these numbers are currently hard-coded, though items on the backlog envisage giving control over these to the user, potentially in the form of a slider to allow the user to determine "how common" verses should be. E.g. we could allow a user to say at least 3 words should be common. This search is defined for a single verse input. Where several verses are given, the result is undefined (though STEP will try and cope gracefully)
exactform	exactForm=ησχυναν	STEP URLs support the full unicode set and as a result the URL can contain full Greek and Hebrew. This search searches for the exact form against all forms found in the 'specific forms' STEP data set (this comprises various Greek NT and Hebrew OT texts as well as the LXX). These forms are crossed referenced against strong numbers and then used to search the selected resources

Note:

When a selected resource does not contain strong numbers, STEP will carry out the search on the ESV but display the results from the selected resources. This obviously means that the results will not be clickable.
When passing full unicode, STEP may decide to remove cantillation/pointing/accents/vowels depending on options and searches to ensure search results are found correctly. Unicode is also normalised at index time. This means the different combinations of characters in the Unicode word will not affect the results.

Combining data types

With powerful individual searches comes the power of combining searches. Combining terms (a term is something like type=data) allows the following operations:

Looking up a specific Bible passage
Restricting a search to a portion of the Bible (e.g to the book of Genesis, or several books, etc.)
Refining searches of the kind (e.g. carrying out one search, then reducing the results by another, etc.).
Combining different types of searches to get great results

A few rules govern how a 'command line' is interpreted. A 'command line' is the entries q paramater (e.g. reference=Genesis.1|version=ESV|version=NIV|strong=H0001)

Data types are combined with the pipe character: |

Governing rules

Defaults for missing parts

All 'lookups' (whether a search for a term or displaying the Bible scriptures to display on screen) relies at minimum on 2 key elements:

A "version" (i.e. a Bible or Commentary).
A reference

If the version is omitted in the URL, the ESV is assumed. If the reference is omitted in the URL, then one of two things happens:

if there are proper search terms (i.e. not version= and not reference=) in the URL, the search will be defaulted to the entire module. A command line of "version=NIV|version=ASV|text=Abraham", then the word Abraham is searched for all references between Genesis and Revelation
If there are not any proper search terms, then the first chapter of the selected text (or ESV if there are no selected versions).

Order of the command line

Furthermore, the order of items may affect the results. In other words, the elements in the command line are a list, not a set. STEP may decide to re-order these to optimize the search order. However, the order is particular important for all version= data elements. The first version= token identifies the versification.

The below example illustrates this. (OHB is the Hebrew text)

version=OHB|reference=Psalm.3.2
version=ESV|reference=Psalm.3.2
version=OHB|version=ESV|reference=Psalm.3.2
version=ESV|version=OHB|reference=Psalm.3.2

The following observations can be drawn:

The blue command lines are identical in meaning
The red command lines are identical in meaning
The blue lines refer to a different verse to the red lines.

This is because the OHB module numbers verse 1 in the Psalms as the canonical Psalm heading.

STEP has very strong support for versifications and supports a growing number of versifications. This is always done transparently. This means STEP can support searching across Bibles that are made of different versification. STEP can also display parallel views or interlinears and will transparently line up Psalm 3.1 in the Hebrew with Psalm 3.2 of the English text.

Options

Together with the search query (q=...), one can specify a set of options. These are used to adjust the display of search query. These are only used during Bible text retrievals and not during search results displays. In terms of the user interface, these are triggered by selecting the options from the 'cog menu'.

Note: Some options are defaulted if the options parameter is missing. Also some options (such as Words of Christ) are only available for some Bibles). If the option is not applicable, it will simply be ignored.

The following options are currently available:

Initial	Meaning	Defaulted	Availability
H	Display headings	Y	All
V	Display verse numbers	Y	All
L	Display each verse on a separate line	N	All
R	Displays Jesus's words in red	N	Some modules only
E	Vocabulary in English interlinear	N	Strong-tagged Bibles If multiple Bibles are selected, all Bibles require strong tagging.
A	Ancient vocabulary interlinear	N	Strong-tagged Bibles If multiple Bibles are selected, all Bibles require strong tagging.
T	Transliterated vocabulary interlinear	N	Strong-tagged Bibles If multiple Bibles are selected, all Bibles require strong tagging.
D	Divides Hebrew words into colours for each segment (currently alternates between 2 colours)	N	OHB only
G	Displays all Greek accents	Y	Greek texts only
U	Displays all Hebrew vowels	Y	Hebrew texts only
P	Displays all Hebrew cantillation	N	Hebrew texts only
N	Displays notes and cross references	Y	Robinson-tagged texts only
M	Displays Grammar (morphology) as an interlinear	N	Robinson-tagged texts only
C	Colour code Grammar	N	Robinson-tagged texts only

In order to obtain the currently available versions, there are two options, the first of which is preferred (though not always possible)

Read the step.keyedVersions variable from the browser's javascript window context.
Until now, the only consumer of web services is STEP itself. The following call was used in a previous version and there are currently no consumers: http://<step-server>/rest/module/getAllModules/

It is usually recommended to leave the options out on the first call and allow the user to select the options through the cog menu.

Different display modes

STEP displays the Bible, commentaries and search results in different ways. There are 5 major ways of displaying these and all of them can be overridden through the 'cog menu'.

Option	Meaning	Default conditions
NONE (or left blank)	A single version is displayed	A single Bible or commentary is selected
INTERLEAVED	Versions are displayed verse by verse in lines. ESV v1 a b c KJV v1 a b c -------------- ESV v2 a b c KJV v2 a b c	If two or more Bibles and/or commentaries are specified and at least one of them does not have strong tagging. (Commentaries never have strong tagging!).
INTERLEAVED_COMPARE	Similar to INTERLEAVED but highlights differences between versions. Where three or more versions are selected, the first version is compared to the other two. For three versions (A,B,C), the display will show A-B, A-C (i.e. 4 instances of each verse)	Never
COLUMN	Similar to INTERLEAVED but in a column/tabular format where each row is a verse and each column is a different version.	Never
COLUMN_COMPARE	Similar to INTERLEAVED_COMPARE and COLUMN. Displays in verses as rows and Bibles/commentaries as columns. Where three or more Bibles/commentaries are selected, the first resource is repeated. E.g. for 4 versions, A,B,C,D, 6 columns are displayed: A,B,A,C,A,D	Never
INTERLINEAR	Interlinear	If two or more Bibles are selected and all of them are tagged with strong numbers.

Integration via the URL