Export and API documentation

Exporting DiRT entries

CSV

If you’re just interested in downloading records from DiRT, you don’t need to use the API. You can simply use the “CSV” link at the bottom of any of the browsing / searching lists of tools.

Description: 

CSV export on DiRT

This will produce a comma-separated value ("CSV") export listing the tools matching your query. Fields are separated from one another by commas, and each field's value is enclosed in double quotes (").

Depending on your browser, this CSV export will either be downloaded to your computer, or will appear in a browser window or tab.

The CSV export will include the following fields:

- Title

- Description

- Date the tool profile was last updated (month/day/year)

- Code license

- Cost

- Cost bracket

- Depends on (name of the tool for which the current tool is a module, plugin or add-on)

- Developer

- Funding source(s)

- Licensing options

- Platform

- Status (development status)

- TaDiRAH goals & methods

- TaDiRAH research objects

- TaDiRAH techniques

- Tags

- TAPoR link (for text analysis tools)

- Webpage

- DiRT URL

If you have applied any of the filters at the top of the screen, those filters will be reflected in the CSV export.

JSON

If you would like a JSON export of all the tools in DiRT, there’s a “Download JSON” link at the bottom of the All Tools page (Tools -> All Tools).

Note that the JSON export is not affected by your choice of search filters, unlike the CSV export.

The JSON download may take some time to load -- please be patient.


Description: 

JSON export on DiRT

API access

DiRT also provides Application Programming Interface (API) access. This provides additional capabilities to retrieve data from DiRT, beyond the CSV and JSON exports. To request an API key, please contact us.

The DiRT API is a read-only, REST-based API, consisting of a set of HTTP GET requests. Its endpoint (the beginning of each URL in the API) is 

http://dirtdirectory.org/publicapi/

Requests can return data as either JSON or XML.

Much of the metadata about DiRT tools is stored using the Drupal “taxonomy” system, which provides controlled and uncontrolled vocabularies. Unlike the CSV and JSON exports, the API returns the term ID (tid) value for each of these terms, and you have to do a separate lookup to match a term ID to its human-readable name.

The API has the following resources:

search_node

Used for searching all DiRT site content (tools, reviews, news items, etc.) that contains the specified search terms

How to use it:

GET http://dirtdirectory.org/publicapi/search_node/retrieve.json?api-key=EXAMPLE-API-KEY&keys=text

This returns all content (including announcements and news, in addition to tools) that contains the terms included under “keys” (here, “text”). You can separate multiple terms using %20 (e.g.

GET http://dirtdirectory.org/publicapi/search_node/retrieve.json?api-key=EXAMPLE-API-KEY&keys=document%20wiki

to search for content that includes the terms “document” and “wiki”)

 

entity_node

 

Used to retrieve content from DiRT. You can specify which fields to return, and/or you can limit the results to ones that meet certain criteria.

Examples:

http://dirtdirectory.org/publicapi/entity_node.json?api-key=EXAMPLE-API-KEY&page=0&pagesize=80&sort=title&direction=DESC&simple=1¶meters[type]=item

This retrieves json (entity_node.json) of the first (page=0) 80 (pagesize=80) tool listings (parameters[type]=item), sorted using the title (sort=title) in descending alphabetical order (direction=DESC), using the “simple” display (simple=1).

Here’s an example result:

[{"vid":"2560","uid":"8","title":"Zotpress","log":"","status":"1","comment":"2","promote":"0","sticky":"0","vuuid":"04d316f2-e5ad-4e38-ba9e-71644444e1a4","ds_switch":"","nid":"97","type":"item","language":"en","created":"1321155832","changed":"1419881779","tnid":"0","translate":"0","uuid":"5345f2df-0850-4716-b1ef-09d049816a19","revision_timestamp":"1419881779","revision_uid":"8","body":{"en":[{"value":"Zotpress is a WordPress plugin that enables users to easily add <a href="\&quot;/resources/zotero\&quot;">Zotero</a> citations to a WordPress site by using a special syntax that turns a Zotero citation key into a well-formatted inline citation and bibliography, based on the data stored in Zotero.","summary":"","format":"filtered_html","safe_value":"

Zotpress is a WordPress plugin that enables users to easily add <a href="\&quot;/resources/zotero\&quot;" rel="\&quot;nofollow\&quot;">Zotero</a> citations to a WordPress site by using a special syntax that turns a Zotero citation key into a well-formatted inline citation and bibliography, based on the data stored in Zotero.

\n","safe_summary":""}]},"field_platform":{"und":[{"value":"web"}]},"field_developer":{"und":[{"tid":"184"}]},"field_cost":{"und":[{"value":"free"}]},"field_tags":{"und":[{"tid":"87"},{"tid":"185"},{"tid":"117"}]},"field_webpage":{"und":[{"url":"<a href="http://wordpress.org/plugins/zotpress/","title":null,"attributes":[]">http://wordpress.org/plugins/zotpress/","title":null,"attributes":[]</a>}]},"field_dependency":{"und":[{"nid":"92"}]},"field_categories":{"und":[{"tid":"17"},{"tid":"18"}]},"field_license":{"und":[{"tid":"1424"}]},"field_tool_status":[],"field_screenshot":{"und":[{"fid":"519","uid":"1577","filename":"zotpressScreenshot.jpg","uri":"public://screenshots/zotpressScreenshot.jpg","filemime":"image/jpeg","filesize":"69092","status":"1","timestamp":"1414900540","uuid":"a9603d18-acc3-4f85-a456-8409203f7612","rdf_mapping":[],"alt":"Zotpress screenshot","title":"","width":"520","height":"305"},{"fid":"520","uid":"1577","filename":"zotpressScreenshotCitations.jpg","uri":"public://screenshots/zotpressScreenshotCitations.jpg","filemime":"image/jpeg","filesize":"64425","status":"1","timestamp":"1414900540","uuid":"d94e3103-efef-42fc-a876-55a1ce045342","rdf_mapping":[],"alt":"Zotpress screenshot showing in-text citations","title":"","width":"520","height":"305"}]},"field_tadirah_goals_methods":{"und":[{"tid":"1603"},{"tid":"1608"}]},"field_tadirah_research_objects":{"und":[{"tid":"2136"}]},"field_funding_sources":[],"field_good_for_beginners":{"und":[{"value":"1"}]},"field_tapor":[],"field_reviewed":{"und":[{"value":"0"}]},"field_cost_bracket":[],"field_licensing":[],"field_tadirah_techniques":{"und":[{"tid":"2180"}]},"field_logo":{"und":[{"fid":"518","uid":"1577","filename":"zotpressLogo.png","uri":"public://logos/zotpressLogo.png","filemime":"image/png","filesize":"8946","status":"1","timestamp":"1414900540","uuid":"21b5c58b-34ee-4e60-b9f1-17f848ec07df","rdf_mapping":[],"alt":"","title":"","width":"120","height":"121"}]},"field_twitter_user":[],"rdf_mapping":{"rdftype":["sioc:Item","foaf:Document"],"title":{"predicates":["dc:title"]},"created":{"predicates":["dc:date","dc:created"],"datatype":"xsd:dateTime","callback":"date_iso8601"},"changed":{"predicates":["dc:modified"],"datatype":"xsd:dateTime","callback":"date_iso8601"},"body":{"predicates":["content:encoded"]},"uid":{"predicates":["sioc:has_creator"],"type":"rel"},"name":{"predicates":["foaf:name"]},"comment_count":{"predicates":["sioc:num_replies"],"datatype":"xsd:integer"},"last_activity":{"predicates":["sioc:last_activity_date"],"datatype":"xsd:dateTime","callback":"date_iso8601"}},"translations":{"original":"en","data":{"en":{"entity_type":"node","entity_id":"97","language":"en","source":"","uid":"8","status":"1","translate":"0","created":"1419881779","changed":"1419881779","revision_id":null}}},"cid":"0","last_comment_timestamp":"1321155832","last_comment_name":"","last_comment_uid":"8","comment_count":"0","name":"quinnanya","picture":"0","data":"a:2:{s:7:\"overlay\";i:1;s:7:\"contact\";i:0;}"},

The same, without the “simple” display:

[{"vid":"2560","uid":"8","title":"Zotpress","log":"","status":"1","comment":"2","promote":"0","sticky":"0","vuuid":"04d316f2-e5ad-4e38-ba9e-71644444e1a4","ds_switch":"","nid":"97","type":"item","language":"en","created":"1321155832","changed":"1419881779","tnid":"0","translate":"0","uuid":"5345f2df-0850-4716-b1ef-09d049816a19","revision_timestamp":"1419881779","revision_uid":"8","body":{"en":[{"value":"Zotpress is a WordPress plugin that enables users to easily add <a href="\&quot;/resources/zotero\&quot;">Zotero</a> citations to a WordPress site by using a special syntax that turns a Zotero citation key into a well-formatted inline citation and bibliography, based on the data stored in Zotero.","summary":"","format":"filtered_html","safe_value":"

Zotpress is a WordPress plugin that enables users to easily add <a href="\&quot;/resources/zotero\&quot;" rel="\&quot;nofollow\&quot;">Zotero</a> citations to a WordPress site by using a special syntax that turns a Zotero citation key into a well-formatted inline citation and bibliography, based on the data stored in Zotero.

\n","safe_summary":""}]},"field_platform":{"und":[{"value":"web"}]},"field_developer":{"und":[{"tid":"184"}]},"field_cost":{"und":[{"value":"free"}]},"field_tags":{"und":[{"tid":"87"},{"tid":"185"},{"tid":"117"}]},"field_webpage":{"und":[{"url":"<a href="http://wordpress.org/plugins/zotpress/","title":null,"attributes":[]">http://wordpress.org/plugins/zotpress/","title":null,"attributes":[]</a>}]},"field_dependency":{"und":[{"nid":"92"}]},"field_categories":{"und":[{"tid":"17"},{"tid":"18"}]},"field_license":{"und":[{"tid":"1424"}]},"field_tool_status":[],"field_screenshot":{"und":[{"fid":"519","uid":"1577","filename":"zotpressScreenshot.jpg","uri":"public://screenshots/zotpressScreenshot.jpg","filemime":"image/jpeg","filesize":"69092","status":"1","timestamp":"1414900540","uuid":"a9603d18-acc3-4f85-a456-8409203f7612","rdf_mapping":[],"alt":"Zotpress screenshot","title":"","width":"520","height":"305"},{"fid":"520","uid":"1577","filename":"zotpressScreenshotCitations.jpg","uri":"public://screenshots/zotpressScreenshotCitations.jpg","filemime":"image/jpeg","filesize":"64425","status":"1","timestamp":"1414900540","uuid":"d94e3103-efef-42fc-a876-55a1ce045342","rdf_mapping":[],"alt":"Zotpress screenshot showing in-text citations","title":"","width":"520","height":"305"}]},"field_tadirah_goals_methods":{"und":[{"tid":"1603"},{"tid":"1608"}]},"field_tadirah_research_objects":{"und":[{"tid":"2136"}]},"field_funding_sources":[],"field_good_for_beginners":{"und":[{"value":"1"}]},"field_tapor":[],"field_reviewed":{"und":[{"value":"0"}]},"field_cost_bracket":[],"field_licensing":[],"field_tadirah_techniques":{"und":[{"tid":"2180"}]},"field_logo":{"und":[{"fid":"518","uid":"1577","filename":"zotpressLogo.png","uri":"public://logos/zotpressLogo.png","filemime":"image/png","filesize":"8946","status":"1","timestamp":"1414900540","uuid":"21b5c58b-34ee-4e60-b9f1-17f848ec07df","rdf_mapping":[],"alt":"","title":"","width":"120","height":"121"}]},"field_twitter_user":[],"rdf_mapping":{"rdftype":["sioc:Item","foaf:Document"],"title":{"predicates":["dc:title"]},"created":{"predicates":["dc:date","dc:created"],"datatype":"xsd:dateTime","callback":"date_iso8601"},"changed":{"predicates":["dc:modified"],"datatype":"xsd:dateTime","callback":"date_iso8601"},"body":{"predicates":["content:encoded"]},"uid":{"predicates":["sioc:has_creator"],"type":"rel"},"name":{"predicates":["foaf:name"]},"comment_count":{"predicates":["sioc:num_replies"],"datatype":"xsd:integer"},"last_activity":{"predicates":["sioc:last_activity_date"],"datatype":"xsd:dateTime","callback":"date_iso8601"}},"translations":{"original":"en","data":{"en":{"entity_type":"node","entity_id":"97","language":"en","source":"","uid":"8","status":"1","translate":"0","created":"1419881779","changed":"1419881779","revision_id":null}}},"cid":"0","last_comment_timestamp":"1321155832","last_comment_name":"","last_comment_uid":"8","comment_count":"0","name":"quinnanya","picture":"0","data":"a:2:{s:7:\"overlay\";i:1;s:7:\"contact\";i:0;}"},

You can also choose which fields you want returned. For instance, if you want a list of titles and webpages for the tools:

GET http://dirtdirectory.org/publicapi/entity_node.json?api-key=EXAMPLE-API-KEY&amp;page=0&amp;pagesize=80&amp;sort=title&amp;direction=DESC¶meters[type]=item&amp;fields=title,field_webpage

The first result from this query is:

[{"title":"Zotpress","field_webpage":{"und":[{"url":"http://wordpress.org/plugins/zotpress/","title":null,"attributes":[]}]}},

You can also use field values to limit the result of your query. By adding in parameters[title]=Drupal:

GET http://dirtdirectory.org/publicapi/entity_node.json?api-key=EXAMPLE-API-KEY&amp;page=0&amp;pagesize=80&amp;sort=title&amp;direction=DESC¶meters[type]=item¶meters[title]=Drupal&amp;fields=title,field_webpage

there is a single result, the title and webpage for the tool Drupal:

[{"title":"Drupal","field_webpage":{"und":[{"url":"https://www.drupal.org/","title":null,"attributes":[]}]}}]

The options you can use for the parameters or fields attributes are:

- type: the Drupal content type; to retrieve tools, use the value “item”

- title: the name of the tool

- body: the description of the tool

- webpage: the URL of the tool

- platform: options are windows, mac, linux, web, android, ios, and other

- cost: options are free, paid, other

- TAPoR: the URL of the tool’s corresponding profile on TAPoR

 

There are numerous other options that will return, or will require you to provide, a term ID (tid):

- field_tool_status: the development status of the tool

- field_developer: the developer of the tool

- field_funding_sources: the sources of funding that support the tool

- field_cost_bracket: options indicating how expensive a tool is

- field_licensing: licensing options (e.g. free trial, educational discount, etc.)

- field_tadirah_goals_methods: The TaDiRAH goals and methods associated with the tool

- field_tadirah_research_objects: the object(s) the tool acts upon

- field_tadirah_techniques: The specific technique(s) associated with the tool

- field_license: The software license associated with the tool

 

 

taxonomy_vocabulary

 

This allows you to retrieve the vid (vocabulary ID) for the taxonomies on DiRT.

 

How to use it: 

http://dirtdirectory.org/publicapi/taxonomy_vocabulary.json?api-key=EXAMPLE-API-KEY

The first result is:

[{"vid":"7","name":"Tool status","machine_name":"tool_status","description":"","hierarchy":"0","module":"taxonomy","weight":"0","language":"und","i18n_mode":"1","uri":"http://dirtdirectory.org/publicapi/taxonomy_vocabulary/7"},

 

taxonomy_term

 

This allows you to retrieve the tid (term ID) for terms within a defined vocabulary, using the vid (vocabulary ID). For instance, this will return the first 80 terms within the “tool status” vocabulary, which has the vid 7 (see example above).

GET http://dirtdirectory.org/publicapi/taxonomy_term.json?api-key=EXAMPLE-API-KEY¶meters[vid]=3&amp;pagesize=80&amp;sort=name&amp;direction=ASC

The results are:

[{"tid":"1177","vid":"7","name":"No longer supported","description":"This tool is available, but no longer supported by its developer.","format":"filtered_html","weight":"3","language":"und","i18n_tsid":"0","uuid":"0e56c37d-6ce6-4f34-b6e9-353bb8211974","uri":"http://dirtdirectory.org/publicapi/taxonomy_term/1177"},{"tid":"1176","vid":"7","name":"Active","description":"This tool is active and able to be used.","format":"filtered_html","weight":"2","language":"und","i18n_tsid":"0","uuid":"22683c54-fa1e-440d-8ce1-29a74ed825f9","uri":"http://dirtdirectory.org/publicapi/taxonomy_term/1176"},{"tid":"1175","vid":"7","name":"Beta","description":"This tool is available to use, but in a beta release.","format":"filtered_html","weight":"1","language":"und","i18n_tsid":"0","uuid":"646230bb-799c-40e3-9b3f-b2b9e1a33c57","uri":"http://dirtdirectory.org/publicapi/taxonomy_term/1175"},{"tid":"1174","vid":"7","name":"In development","description":"This tool is currently being developed and not yet ready for use.","format":"filtered_html","weight":"0","language":"und","i18n_tsid":"0","uuid":"a2a78925-df8f-43db-9d0c-3321d2273678","uri":"http://dirtdirectory.org/publicapi/taxonomy_term/1174"}]