Plain Text Reference Parser

The plain text reference parser does it's best to take plain text strings like "Alma1-2;4-5:10;jas1:5-6" and return a programmatical response of the selected books, chapters, and verses. Which response can then be used to query for those selected books if desired.

Note: The Plain Text Parser is currently in beta, and is in the process of being improved and expanded. If you find a parsing error, please submit it to this google form so that we can make the parser even better.

Note: For all API url examples the url given is appended to the base url. The base url will include information like the desired API version, denomination, and language of the resource that you are requesting. If you simply append the endpoint to "openscriptureapi.org" you will get a 404 error.

GET/referencesParser

Parse a reference string

This endpoint allows you to convert a plain text string into a set of books, chapters, and verses. Additionally, the endpoint also returns whether the reference string is valid, and if it is valid then a standardized reference string is also returned as well.

Required query parameters

Name
reference
Type
string
Description
The string that should be parsed
Name
api-key
Type
string
Description
The API Key associated with your account. Learn more at API Keys

Response

Name
references
Type
array
Description
An array of book objects that were referenced in the reference string
Name
references[].book
Type
array
Description
The book id of the referenced book. This id can be used to obtain the book via the books endpoint
Name
references[].chapters
Type
array
Description
An array of chapter objects, which are the chapters referenced within the given book
Name
references[].chapters[].start
Type
number
Description
The starting chapter for this chapter segment
Name
references[].chapters[].end
Type
number
Description
The ending chapter for this chapter segment. Note: If only one chapter was referenced for this chapter segment, then the start and end values will be the same
Name
references[].chapters[].verses
Type
array
Description
An array of verse segments which were referenced for the end chapter. If no verses were referenced than this array will be empty
Name
references[].chapters[].verses[].start
Type
number
Description
The starting verse for this verse segment
Name
references[].chapters[].verses[].end
Type
number
Description
The ending verse for this verse segment. Note: If only one verse was referenced for this verse segment, then the start and end values will be the same
Name
prettyString
Type
string
Description
A standardized string of the provided references, with correct spacing, etc.
Name
valid
Type
boolean
Description
A boolean value of whether the provide reference string was able to be parsed. If false an error attribute will be provided with details as to why the reference string couldn't be parsed
Name
error
Type
string
Description
If the valid attribute is false, this will be an error string of why the reference couldn't be parsed

Response for "Alma1-2;4-5:10;jas1:5-6"

{
  "references": [
    {
      "book": "alma",
      "chapters": [
        {
          "start": 1,
          "end": 2,
          "verses": []
        },
        {
          "start": 4,
          "end": 5,
          "verses": [
            {
              "start": 10,
              "end": 10
            }
          ]
        }
      ]
    },
    {
      "book": "james",
      "chapters": [
        {
          "start": 1,
          "end": 1,
          "verses": [
            {
              "start": 5,
              "end": 6
            }
          ]
        }
      ]
    }
  ],
  "prettyString": "Alma 1-2; 4:5-19; James 1:5-6",
  "valid": true
}

Note: the Open Scripture API is still in beta, and these resources/endpoints can change at any time