American Bible Society

DONATE NOW

Switch to mobile version

Back to BibleSearch

Developer Tools: API

Widget

Highlighter - Beta

API

Application Programming Interface (API)

Taggings

Taggings associate tags with verses and are owned by users.

Note: You may only view or manipulate your own taggings.

List

GET /user/taggings.xml

Returns all of your taggings. All of your tags and tagged verse references are included in the output of this request.

Example:

Request
GET https://biblesearch.americanbible.org/user/taggings.xml
Response
<?xml version="1.0" encoding="utf-8"?>
<taggings>
  <tagging id="701">
    <id>701</id>
    <user_id>12</user_id>
    <tag_id>257</tag_id>
    <updated_at>2010-10-29 14:03:39</updated_at>
    <created_at>2010-10-29 14:03:39</created_at>
    <references>
      <reference>
        <start>GNT:John.3.18</start>
        <end>GNT:John.3.18</end>
      </reference>
    </references>
    <tag id="257">
      <id>257</id>
      <name><![CDATA[son of god]]></name>
    </tag>
  </tagging>
  <tagging id="702">
    <id>702</id>
    <user_id>12</user_id>
    <tag_id>258</tag_id>
    <updated_at>2010-10-29 14:04:43</updated_at>
    <created_at>2010-10-29 14:04:43</created_at>
    <references>
      <reference>
        <start>GNT:John.3.27</start>
        <end>GNT:John.3.27</end>
      </reference>
    </references>
    <tag id="258">
      <id>258</id>
      <name><![CDATA[possessions]]></name>
    </tag>
  </tagging>
</taggings>

GET /user/taggings/#{tag_name}.xml

Returns all of your taggings for the specified tag. The specified tag and all verse references you have tagged with it are included in the output of this request. Make sure you properly URL encode the tag name in the URL used for this request.

Example:

Request
GET https://biblesearch.americanbible.org/user/taggings/possessions.xml
Response
<?xml version="1.0" encoding="utf-8"?>
<taggings>
  <tagging id="702">
    <id>702</id>
    <user_id>12</user_id>
    <tag_id>258</tag_id>
    <updated_at>2010-10-29 14:04:43</updated_at>
    <created_at>2010-10-29 14:04:43</created_at>
    <references>
      <reference>
        <start>GNT:John.3.27</start>
        <end>GNT:John.3.27</end>
      </reference>
    </references>
    <tag id="258">
      <id>258</id>
      <name><![CDATA[possessions]]></name>
    </tag>
  </tagging>
</taggings>

Show

GET /taggings/#{tagging_id}.xml

Returns the tagging with the specified tagging ID. The tagging ID is a number and is returned when a tagging is listed. The associated tag and all of its verse references are included in the output of this request.

Example:

Request
GET https://biblesearch.americanbible.org/taggings/702.xml
Response
<?xml version="1.0" encoding="utf-8"?>
<taggings>
  <tagging id="702">
    <id>702</id>
    <user_id>12</user_id>
    <tag_id>258</tag_id>
    <updated_at>2010-10-29 14:04:43</updated_at>
    <created_at>2010-10-29 14:04:43</created_at>
    <references>
      <reference>
        <start>GNT:John.3.27</start>
        <end>GNT:John.3.27</end>
      </reference>
    </references>
    <tag id="258">
      <id>258</id>
      <name><![CDATA[possessions]]></name>
    </tag>
  </tagging>
</taggings>

Create

POST /user/taggings.xml

Creates a tagging resource for the tag and verse reference you pass to it in the body of your XML request. You must pass either the tag name node or id node with your request.

The verse reference must have both a start and an end node, each representing a verse id marking the start and end of the passage you would like to tag. To tag a single verse, submit the same verse id as both the start and end values.

Example:

Request
POST https://biblesearch.americanbible.org/user/taggings.xml
Content-Type
application/xml
Body
<tagging>
  <tag>
    <name>peace</name>
  </tag>      
  <references>
    <reference>
      <start>GNT:John.3.18</start>
      <end>GNT:John.3.18</end>
    </reference>
  </references>
</tagging>
Response
<?xml version="1.0" encoding="utf-8"?>
<taggings>
  <tagging id='705'>
    <id>705</id>
    <user_id>12</user_id>
    <tag_id>31</tag_id>
    <updated_at>2010-11-01 14:53:14</updated_at>
    <created_at>2010-11-01 14:53:14</created_at>
    <references>
      <reference>
        <start>GNT:John.3.18</start>
        <end>GNT:John.3.18</end>
      </reference>
    </references>
    <tag id='31'>
      <id>31</id>
      <name><![CDATA[peace]]></name>
    </tag>
  </tagging>
</taggings>

Update

PUT /taggings/#{tagging_id}.xml

Modifies a tagging resource identified by the given ID, with the tag and verse reference you pass to it in the body of your XML request. You may pass either the tag name node or id node with your request to update the tag used for the tagging.

The verse reference must have both a start and an end node, each representing a verse id marking the start and end of the passage you would like to tag. To tag a single verse, submit the same verse id as both the start and end values.

Example:

Request
PUT https://biblesearch.americanbible.org/taggings/12.xml
Content-Type
application/xml
Body
<tagging>
  <tag>
    <name>love</name> <!-- optional -->
  </tag>      
  <references>
    <reference>
      <start>GNT:Acts.8.34</start>
      <end>GNT:Acts.8.36</end>
    </reference>
  </references>
</tagging>
Response
<?xml version="1.0" encoding="utf-8"?>
<taggings>
  <tagging id='705'>
    <id>705</id>
    <user_id>12</user_id>
    <tag_id>267</tag_id>
    <updated_at>2010-11-01 15:09:28</updated_at>
    <created_at>2010-11-01 14:53:14</created_at>
    <references>
      <reference>
        <start>GNT:Acts.8.34</start>
        <end>GNT:Acts.8.36</end>
      </reference>
    </references>
    <tag id='267'>
      <id>267</id>
      <name><![CDATA[generosity]]></name>
    </tag>
  </tagging>
</taggings>

Delete

DELETE /taggings/#{tagging_id}.xml

Deletes the tagging identified by the specified ID. The tagging ID is a number and is returned when a tagging is listed.

Note: The content-type header is not needed for DELETE requests, since you are not sending any XML to the ABS API.

Example:

Request
DELETE https://biblesearch.americanbible.org/taggings/12.xml
Response
[Empty response body]


DELETE /user/taggings/#{tag_name}.xml

You may also delete all of your tags for a given tag name by passing the name in the request URL. Make sure you properly URL encode the tag name in the URL for this request.

Example:

Request
DELETE https://biblesearch.americanbible.org/user/taggings/love.xml
Response
[Empty response body]