Publications   Developer Help

Developer Help

Print This Page Bookmark and Share

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; however, the two different operators cannot be used in the same query.

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>&detail=<not required value>
Parameters/Input:
  • pubid: Retrieve a document based on its government publication identifier.
  • detail: Indicates granularity of detail to return. Valid values are “low” or “high”. A default value of “low” is used if detail is not specified. “Low” corresponds to item metadata while “high” includes item content.
Output Format:
XML
Sample Requests and output:
http://content.samhsa.gov/ext/api/items?pubid=SMA12-4670
http://content.samhsa.gov/ext/api/items?pubid=SMA12-4670&detail=high
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.
  • detail: Indicates granularity of detail to return. Valid values are “low”, “medium”, or “high”. A default value of “low” is used if not specified.
  • 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&detail=medium&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:
  • HTML
  • XML
  • JSON
Sample Requests and output:
http://store.samhsa.gov/api/r/xml/productlist?terms=Idaho
http://store.samhsa.gov/api/r/xml/productlist?start=1&pagelength=10&terms=Alcohol!Alcohol%20Abuse&sortBy=relevance&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/productlist?terms=Awareness~Educators~Webcast
http://store.samhsa.gov/api/r/xml/productlist?terms=Idaho&start=3
API: Get Product Details
Description:
This API provides detail information about a publication available on the SAMHSA store.
API Type:
HTTP (GET) Request
Requests URL Format:
http://store.samhsa.gov/api/r/<output-format>/product?id=<pub-id>
Input:
  • output-format: specify 'xml', 'html', or 'json' to get desired output.
  • pub-id: Publication ID
Output Formats:
  • HTML
  • XML
  • JSON
Sample Requests and output:
http://store.samhsa.gov/api/r/xml/product?id=DVD209
http://store.samhsa.gov/api/r/xml/productlist?start=1&pagelength=10&terms=Alcohol!Alcohol%20Abuse&sortBy=relevance&ascending=false
http://store.samhsa.gov/api/r/html/product?id=DVD209
API: Get Taxonomy Term List
Description:
This API provides list of terms from the SAMHSA taxonomy.
API Type:
HTTP (GET) Request
Requests URL Format:
http://store.samhsa.gov/api/r/xml/termlist?prefix=<prefix>
Input:
  • prefix: Beginning of a term (one or more letters)
Output Formats:
  • XML
  • JSON
Sample Requests and output:
http://store.samhsa.gov/api/r/xml/termlist?prefix=E