How to use the cURL API to Export Registry or Study Data

Site Admins and Site Managers can use the Export cURL API to export data from the Registry or a study in bulk without having to go into Ripple and manually use the Export Tool. Using the Export cURL API Command, users can run a code at any moment to export the data from Ripple and transform and import it into a third-party system. This allows users to more quickly and regularly export the data they need and make sure that data is harmonized across different systems.

What You Need Before You Start:

  • Ripple Site URL 
  • Authorization Key
  • Study ID
  • Time Zone
  • Name of the variables you want to export
  • Name of an excel you want to export the data into
  • Export cURL Command

Mac Users: Export cURL Command:

curl ‘RippleSiteURL/v1/export' \

--header 'Authorization: Basic AuthorizationKey' \

--data-raw 'export-type=StudyId&export-timezone=TimeZone&variableName1=on&variableName2=on&variableName3=on …' > NameofExportedExcel.csv

Window Users: Export cURL Command:

curl ''RippleSiteURL/v1/export''

--header ''Authorization: Basic AuthorizationKey''

--data-raw ''export-type=StudyId&export-timezone=TimeZone&variableName1=on&variableName2=on&variableName3=on …'' > NameofExportedExcel.csv

Steps:

  1. If using a Mac device, open up your Terminal if using a Mac device. If using a Windows device, open up your Command Prompt 
  2. Paste in the Export cURL Command from above
  3. Replace the RippleSiteURL with your Study ID
  4. Find your Authorization Key and replace the AuthorizationKey with your Authorization Key
  5. Replace the StudyId with your study’s ID
  • If you’re exporting from the Registry, use the code “global” in lowercase
  • If you’re exporting from a study, select the Study ID string from the URL (red)

  1. If necessary, replace the Timezone with your Timezone
  2. Replace the variableNames with the name of your variables
  3. If you want to download the data into an Excel, replace the NameofExportedExcel with what you’d like the Excel to be named

Variable Names:

The Export cURL Command variable names are sensitive to spaces and special characters. Typically, spaces are replaced by underscores and custom variables need “cv.” before the variable name. For example, a Custom Variable called “Potential Eligibility” would be written in the command as “cv.potential_eligibility.”

However, there are a few notable exceptions to writing out Ripple pre-set variables.

Variable name in Ripple How it should be written in the Export cURL Command
Events (All or None) Events+%28+All+or+None+%29
Participant Contacts Participant+Contacts
Comments Log Comments+Log
Contact Log Contact+Log
Email Log Email+Log
Consent Log Consent+Log
 

Note on Exporting Survey Data:

Exporting survey data requires additional information and formatting. You can learn how to export survey data using the Export cURL Command here

Example:

The Study’s Data Analyst is working on a report and asked you to compile a list of participants’ first names, last names, global ID, custom ID, status, sex, and race from your Ancillary A Study. Here is what your Export cURL Command will look like:

curl ‘https://supportplayground.ripplescience.org/v1/export' \

--header 'Authorization: Basic ZXhhbXBsZS51c2VyQHJpcHBsZXNjaWVuY2UuY29tOnN1cGVyc2VjcmV0cGFzc3dvcmQxMjMK' \

--data-raw 'export-type=bdHZw2JPpZxvcY6Qv&export-timezone=America%2FChicago&firstName=on&lastName=on&globalId=on&customId=on&statusId=on&sex=on&race=on' > StudyDataExport.csv

Tailor your Export cURL Command!

Make sure to choose the correct cURL command based on your device and match your Site URL, Authorization Key, and Study ID to your Ripple site and permissions.

 

Was this article helpful?
1 out of 1 found this helpful

Comments

1 comment
  • To do this with PHP, you have to manually set the method to "GET" and include the "--data-raw" parameters as POST fields:

    <?php
        // Prepare the URL with query parameters
        $api_operation = 'export';
        $data = array(
            'export-type' => RIPPLE_STUDY_ID, // 'global' or RIPPLE_STUDY_ID.
            'export-timezone' => RIPPLE_TIMEZONE, // already encoded
            'globalId' => 'on',
            'Participant+Contacts' => 'on',
            // ...other fields
        );
       
        // Initialize cURL
        $ch = curl_init();

        // Set the URL and other options for a GET request with POST data (yes, this is poor form but that's how Ripple's API works)
        curl_setopt($ch, CURLOPT_URL, RIPPLE_URL . $api_operation); // It will not work to append the query string to the URL. It must be in POST fields.
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, array(
            "Authorization: Basic " . RIPPLE_USER_HASH // Must already be hashed
        ));
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET'); // Set the request method to GET
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
       
        // Execute the request
        $output = curl_exec($ch);
        $lines = explode("\n", $output); // Split CSV data into lines
        $result = []; // Initialize an empty array to hold the CSV data

        foreach ($lines as $line) {
            if (!empty($line)) {
                $result[] = str_getcsv($line);
            }
        }
        $headers = array_shift($result); // Remove the first row from the result and store it as headers
       
        // Check for errors
        if(curl_errno($ch)) {
            throw new Exception(curl_error($ch));
        }

        // Close the cURL handle
        curl_close($ch);
    ?>
    <table>
                <thead>
                    <tr>
                        <?php foreach ($headers as $header) : ?>
                            <th><?= $header; ?></th>
                        <?php endforeach; ?>
                    </tr>
                </thead>
                <tbody>
                    <?php foreach ($result as $row) : ?>
                        <tr>
                            <?php foreach ($row as $cell) : ?>
                                <td><?= $cell; ?></td>
                            <?php endforeach; ?>
                        </tr>
                    <?php endforeach; ?>
            </table>
    0

Please sign in to leave a comment.