Skip to main content
January, 2018

Implementing Open Referral with Drupal and WordPress

Abhijeet Chavan
Abhijeet Chavan
Chief Technology Officer

Many organizations provide health, legal, and other social services to people in need. If organizations can publish information about the services they provide in a common format, this data can be aggregated and searchable so that people needing assistance can find right organization for their needs. The Open Referral initiative has developed a data interchange format called the Human Service Data Specification (HSDS) for publishing machine-readable data about service providers, their locations, and the services they provide.

How to Implement Open Referral with Drupal and WordPress

For organizations that use the Drupal content management system for maintaining their websites, we have developed openreferral-drupal (ORD), an open source Drupal module to make it possible to publish resource directory data in HSDS format. The ORD module was developed as part of the Drupal for Legal Aid Websites (DLAW) project.

To maintain resource data in the structure that is needed to publish in the HSDS format, Devin Balkind of Sarapis developed a sample database using Airtable, an easy-to-use web database. Anyone can make a copy of the sample dataset and use it to maintain their own HSDS resource data in Airtable.

Sample dataset in Airtable.

The ORD module extracts data from the HSDS Airtable database and publishes it in HSDS format on a Drupal website.

OpenReferral DLAW Configuration

To use the ORD module:

  1. Make a copy of the sample database in Airtable. Make a note of your Airtable <em”>API key and the API Base URL for the database.
  2. Populate the Airtable database with your own data.
  3. Install the ORD module on your Drupal website.
  4. In the ORD module configuration panel set Airtable API key and the API Base URL for the database. Then click Save.

The ORD module will extract data from the AirTable database and generate files as specified in the Open Referral HSDS (v 1.1) format at the following URLs:

(your website domain)/openreferral/datapackage.json
(your website domain)/openreferral/organizations.csv
(your website domain)/openreferral/phones.csv
(your website domain)/openreferral/postal_addresses.csv

The first time one of the above URL is requested, ORD will extract data from the Airtable database, cache the data on the Drupal website, and generate the Openreferral files. Depending on the amount of data in the database, this first step may take a minute or longer. Subsequent requests to the above URLs will be faster.

The ORD module does not automatically update the cache. When you update the Airtable database, click the Purge Cache button on the ORD module configuration panel.

OpenReferral DLAW Configuration

This first version of the ORD module implements only a few features of the HSDS data. I hope others will extend this module and use this approach for other web platforms.

Open Referral for WordPress

We also developed Open Referral WordPress Plugin as a port of ORD for WordPress. I encourage WordPress developers to experiment with and extend this plugin.

Open Referral WordPress Plugin configuration panel

Open Referral Drupal module and WordPress plugin were developed by Abhijeet Chavan and Ki Kim of Urban Insight. Thanks to Devin Balkind of Sarapis for building the Airtable implementation of HSDS v.1.1. and to Greg Bloom of Open Referral for his support. And thanks to the Legal Services Corporation for supporting innovation in legal technology.


Licensed Creative Commons 4.0 BY-SA