Publications Developer Help

Developer Help

Instructions for Developers

SAMHSA offers a simple way for developers to access data in formats that are easy to consume by other websites and systems. APIs are available from the SAMHSA Store as well as from the newly launched content repository, which houses SAMHSA content in XML format.

Many of the API parameters rely on keywords from the SAMHSA taxonomy. The SAMHSA taxonomy is visible within the navigation of the SAMHSA Store, and it is available in full at http://tools.store.samhsa.gov/taxonomy/tr1.htm. In any API that uses the taxonomy, terms may be combined by using an exclamation mark (!) to represent an ‘OR’ operator or a tilde (~) to represent an ‘AND’ operator. There is no limit to the number of terms that can be combined.

The SAMHSA content repository houses XML formatted according to the SAMHSA document type definition (DTD). Details describing the DTD are available at http://tools.store.samhsa.gov/dtd-docs/index.html.

Content Repository APIs

The following APIs are available from the Content Repository.

API: Get SAMHSA document

Description:

Get a SAMHSA document by its publication identifier (Pub ID). The level of detail of the returned document can also be specified.

API Type:

HTTP (GET) Request

Requests URL Format:

http://content.samhsa.gov/ext/api/items?pubid=<required value>

Parameters/Input:

pubid: Retrieve a document based on its government publication identifier.

Output Format:

XML

Sample Request and output:

http://content.samhsa.gov/ext/api/items?pubid=SMA12-4670

API: Search SAMHSA documents

Description:

Retrieve SAMHSA documents based on structured query criteria. The level of detail returned can also be specified. Each returned query will display the start position of the results, the result length and the number of results that match the search criteria. This information can be used to paginate through the result set.

API Type:

HTTP (GET) Request

Requests URL Format:

http://content.samhsa.gov/ext/api/items?<parameter-name-value-pairs>

Parameters/Input:

The following criteria can be applied to the search. At least one “q–” criteria must be specified. When multiple “q–” criteria are specified “AND” logic is applied.

q-title: Search for a string in an article title
q-taxo: Search for an exact match of taxonomy terms. Multiple terms can be specified by using “!” or “~”. Terms separated by “!” indicate “OR” logic is applied, while “~” indicates “AND” logic is applied. Mixing of “!” and “~” is not allowed.
q-text: Search for a string anywhere in an item.
start: The index of the first document that satisfied the query. The default is 1 if not specified.
pagelength: Indicates the maximum number of documents to return. The default is 10 if not specified.

Available Output Formats:

XML

Sample Requests and output:

http://content.samhsa.gov/ext/api/items?q-title=Media
http://content.samhsa.gov/ext/api/items?q-taxo=Recovery Support
http://content.samhsa.gov/ext/api/items?q-text=Treatment
http://content.samhsa.gov/ext/api/items?q-taxo=Recovery Support&q-text=Treatment
http://content.samhsa.gov/ext/api/items?q-taxo=Treatment~Recovery
http://content.samhsa.gov/ext/api/items?q-taxo=Recovery Support&q-text=Treatment&start=21&pagelength=20

SAMHSA Store Developer APIs

The following APIs are available from the SAMHSA Store.

API: Get Website List

Description:

This API allows one to get a list of websites available through the SAMHSA store.

API Type:

HTTP (GET) Request

Requests URL Format:

http://store.samhsa.gov/api/r/<output-format>/websitelist?<parameter-name-value-pairs>

Input:

output-format: Specify either 'xml', 'html', or 'JSON' to get desired output.
terms: Return a combination of one or more terms.
size (alternatively, pagelength): Number of website records desired in the output.
start: Index number of the first website to display as a result.
sortby: Specify one of the following parameters to sort the list of results.
- relevance: Results are sorted by number of shared taxonomy terms; this parameter can only be applied to queries with an OR clause.
- title: Sorts the results by title, in alphabetical order.
- pubdate: Sorts the results chronologically, by date of publication.
ascending: Specify either 'true' or 'false'; sorts the results in ascending order.

Available Output Formats:

HTML
XML
JSON

Sample Requests and output:

http://store.samhsa.gov/api/r/xml/websitelist?terms=Alcohol&size=5
http://store.samhsa.gov/api/r/json/websitelist?start=1&pagelength=50&ascending=false
http://store.samhsa.gov/api/r/json/productlist?start=1&pagelength=10&terms=Alcohol!Alcohol%20Abusee
http://store.samhsa.gov/api/r/html/websitelist?terms=Alcohol!Educator
http://store.samhsa.gov/api/r/html/websitelist?terms=Alcohol!Alcoholism&pagelength=3
http://store.samhsa.gov/api/r/html/websitelist?terms=Alcohol!Alcoholism&start=5

API: Get Product List

Description:

This API allows one to get a list of publications available through the SAMHSA store.

API Type:

HTTP (GET) Request

Requests URL Format:

http://store.samhsa.gov/api/r/<output-format>/productlist?<parameter-name-value-pairs>

Input:

output-format: specify 'xml' or 'html' to get desired output.
term-list: Combination of one or more terms
size (alternatively, pagelength): Number of website records desired in the output
start: Index number of the first website to display as a result.
sortby: Specify one of the following parameters to sort the list of results.
- relevance: Results are sorted number of shared taxonomy terms; this parameter can only be applied to queries with an OR clause.
- title: Sorts the results by title, in alphabetical order.
- subtitle: Results are sorted alphabetically by subtitle.
- pubdate: Sorts the results chronologically, by date of publication.
- rank: Results are sorted by number of copies ordered.
- avgRating: Results are sorted by average publication rating.
- totalRating: Reuslts are sorted by total number of ratings.
- format: Results are sorted by format.
Ascending: Specify either 'true' or 'false'; specifies whether to sort the results in ascending order.

Output Formats: