Referencing Verses

Overview

When API.Bible returns verse content, each verse (and each verse span within rendered content) carries two references:

The Problem

If you are looking to relate extraneous content to a specific verse, you may notice that, for certain translations, there are instances where the id and orgId values for a given verse differ.

What does this mean?

Different Bible translations divide chapters into verses differently. In some instances, you will notice a translation's verse id may be shifted, merged, or split relative to its orgId. This is what we call versification. Because of these versification differences, we use an organizational ID (orgId) as a constant reference point for all verses.

Examples

Matthew 1:20 (Identical)

When a translation numbers its verses identically to the canonical scheme, the two id values returned by the API are the same. For example, the API returns Matthew 1:20 as:

Copy
{
  "id": "MAT.1.20",
  "orgId": "MAT.1.20",
  ...
}

Psalm 3.1 (Mismatched)

When a translation uses a different versification than the canonical scheme, the two id values returned by the API will differ. For example, some translations return Psalm 3.1 as:

Copy
{
  "id": "PSA.3.1",
  "orgId": "PSA.3.2",
  ...
}

Why the Psalms?

Typically, the Psalms are the most common place this discrepancy surfaces. In the Hebrew/organizational versification, a psalm’s superscription (e.g., “A Psalm of David, when he fled from Absalom”) is counted as verse 1. Many translations do not number the superscription, which shifts each verse number up by 1. In this case, what was previously represented as the canonical verse 2 is now this translation's verse 1.

Which ID should you use?

Because of the differences mentioned above, if you are looking to link content to specific verses we highly recommend referencing a verse's orgId rather than its id. The orgId ultimately represents the canonical location of the text represented in this verse, so by using it, you are guaranteed to get the correct verse content regardless of translation.

To request a verse or passage by orgId you can set the use-org-id query paramter to true in your request.

Edge Cases

Multiple verseOrgIds

For some verse spans, you may see intstances where the verseOrgIds field contains multiple IDs. If you are referencing this verse span, it is recommended you relate your content to all relevant verseOrgIds when possible.

Partial Verses

Sometimes, verse ranges will include partial verses. When parsing these ranges, be sure to handle trailing letters (a, b, …) so that partial verses are matched correctly.