17.9.18

(Part 1) Collecting data from NationalBuilder API with OpenRefine

2:12 PM  , , ,


This article is part of a series of tutorials to use NationBuilder API. We wrote them in collaboration with Campaign Gears. NationalBuilder is an online software that helps organizations to coordinate their community. It supports members management, web pages, finances, and online communications. NationalBuilder has an API that gives access to NationalBuilder's core features. 

The NationalBuilder API has extensive documentation and options to explore all available features. Using the API Explorer, you can explore the different API endpoints. These endpoints allow you to review all data available in the NationalBuilder API. You can learn more about the API in the Developer Blog and API Documentation.


The NationalBuilder API documentation provides examples of how to access the API with Ruby, PHP, and Python. In this article, we explain how non-developer can use the API thanks to OpenRefine.  We describe two techniques: one using cURL and OpenRefine and one using only OpenRefine.

Don't hesitate to contact us if you have questions or need help to implement NationBuilder data integration project.
To access to your NationalBuilder data, you need to have the following information:
  • NATION_SLUG: name defined in NationalBuilder when you create your profiles in https://nationbuilder.com/create. 
  • NB_TOKEN: value defined by NationalBuilder when the new account is created. The token provides the credentials access to use NationalBuilder API.

Using cURL

The cURL approach is useful when starting a project from scratch. You can bulk download a list of persons saved in NationBuilder. We use the NATION_SLUG and NB_TOKEN to make an HTTP request to NationalBuilder API. The following code is an example of how you can download to a JSON file the first 10 people (using the limit= parameter) using the People API.

Please remember to change NATION_SLUG and NB_TOKEN with the values from your account:

curl -X GET "https://NATION_SLUG.nationbuilder.com/api/v1/people?limit=10&access_token=NB_TOKEN" -H "Content-Type: application/json" > people.json

You can run the code a terminal using a simple cURL command. The file "people.json" is saved in the same directory where you ran the command in your terminal. The data in the file is in JSON format, while it is hard to read for humans in that way, OpenRefine can help us
  1. Create a new project in OpenRefine using recently downloaded file "people.json"
  2. Load the file 
  3. In the section "Configure Parsing Options" move the cursor and select the area inside property ''results'', and Click Create Project

Using OpenRefine

In that case, we assume you want to enrich an existing list with information available from NationBuilder.  You already have a project with the _id of each person in NationBuilder.  

  1. Open your project and identify the column with the NationBuilder ID, in your case it is "_ - id"
  2. Call the NationBuilder API by selecting the column "_ - id" -> "Edit column" -> "Add column by fetching URLs..."
  3. In this new window we can configure the following options:
    1. "New column name": name for the new column
    2. Click on the "Show" button next to "HTTP headers to be used when fetching URLs" for more options.
    3. Click on "Accept": and add the value "application/json"
    4. Insert the next GREL expression in section "Expression": "https://NATION_SLUG.nationbuilder.com/api/v1/people/"+value+"?access_token=NB_TOKEN"
  4. Press button "OK" and wait until the request is completed. You can reduce the Throttle delay to speed up the process.
OpenRefine creates a new column with all the details for each person in JSON format.


For more details and how to parse that new column, you can follow the module 5.5 (Data Enrichment Parsing API Results) of the free OpenRefine course.