Topics, rebuilt

2.0.0-rc.7 through rc.9

We found a hole in the topics data. We fixed the hole and we added what clients needed to show it off. Two releases. rc.8 and rc.9.

The hole

The nave-torrey topic edition was incomplete. It came from an upstream derived layer, and that layer had lost a lot on the way. About 40% of Nave’s references were gone. The topic jesus, the christ served 19 of its 2,753 citations. The topic god served 132 of 2,702. Labels were cut off, like “OF MAN FOR GO.” Every whole-chapter reference was missing.

We threw out that layer. We re-imported from the raw CCEL texts of Nave’s and Torrey’s books.

Here’s what the edition holds now.

• 5,747 topics
• 94,753 citations
• 270,236 verse rows

Whole-chapter references and cross-chapter references are expanded to verses. Sub-items carry a combined label, like “Instances of love for Jesus — Mary.” All-caps headings are sentence-cased.

rc.9 finished the job. It repaired an OCR zero in the source text (0F man for Jesus is now Of man for Jesus) without touching real numbers. It fixed two Torrey references that had imported with no verses. Genesis 36:31-29 is now 36:31-39. 2 Samuel 2:4-1 is now 2 Samuel 2:4 – 1 Kings 2:11, expanded across both books. It also expanded Wisdom 2. Every nave-torrey citation now has verse rows.

Counts in one call

GET /topics?counts=true returns citation_count and verse_count for every topic. One grouped query. Before this, a client that wanted a count next to each topic name had to ask once per topic. The default response hasn’t changed.

Verse text inline

GET /topics/{topic}?hydrate=true&version=eng_kjv returns the text of each verse with the citations. The default version is eng_kjv. No second round trip for every reference.

rc.9 tightened one thing. If you pass a version that doesn’t exist, you get 404 version_not_found. It used to return 200 with no text, and you couldn’t tell a bad version from a verse with nothing to show. A malformed code is still 400 invalid_version_code. A version we can’t serve is still 503. And version is still ignored unless hydrate=true.

Rank and see-also

Citations in the curated iqbible edition now carry a rank. One is the most relevant. Nave and Torrey citations carry none, because their order is the order of the source and not a ranking.

GET /topics/{topic} also returns see_also. That’s the list of topics Nave and Torrey point to from a heading. It’s an empty array for the curated edition.

Less noise

The curated topics repeated themselves. The topic homosexuality listed 1 Corinthians 6:9-11, then 6:9-10, then 6:9. Same verses three times. We dropped a citation when a higher-ranked citation in the same topic already covered it. That cut 820 citations across 92 topics. Ranks were renumbered from 1 to N.

What you need to do

Nothing breaks. New fields are additions. If you cache topic responses, expect the nave-torrey topics to be much bigger and clear the cache. If you paged through jesus, the christ and thought 19 citations was the whole story, it wasn’t.

The IQ Bible App already uses all of this. See the App v1.26 release notes for how it looks on screen.

Already building against the API? Check it out in the developer portal and keep going. Not yet? Get a free API key and make your first request today.

We build the biblical data infrastructure. You build the tools that help people encounter God’s Word. Build boldly, build well.