Learn about SwipeGuide’s Data API and what data can be extracted from it.

The Data API will help you do the following:

• Integrate your SwipeGuide data with your visualization and storage systems, like Grafana, Power BI, Snowflake, or Tableau.
• Extract all relevant data from SwipeGuide to your data lake (eg. Azure) for custom reporting. Streamline your data to improve processes and keep higher management informed about progress directly in your centralized reporting.
• Streamline your data to improve processes and keep management informed about progress directly in your centralized reporting.

Table of Contents

Getting Started

Our REST API can be used for extracting data in CSV or JSON format. 

To get started, we will share with you an authentication token so you're able to access the API. Please contact your Customer Success Manager for more details.

Choosing synchronous vs Async version of the Data API

Our recommendation is to use the newer Async version of the API due to several advantages that it has over the synchronous version.

The Async version of the Data API returns a CSV file whereas the synchronous version returns a JSON response. Additionally, the Async version has a higher row limit of 1 million rows compared to the 100k row limit of the synchronous version, thus reducing the need for response pagination.

One limitation of the async version is that the field names are not “pretty” versions. For example the field called “workspace_name” can be called as “Workspace Name” in the synchronous version and returned with the same "pretty" name. 

Authentication

We use a bearer token authentication method, which provides a secure way to access your data. Your REST client requires a bearer access token to authenticate to the API. The access token is a string, which you must include in the Authorization header to authorize your API requests. In order to receive an authentication token, please reach out to your SwipeGuide customer success manager.

Async Version of Data API

Using this version of the Data API consists of the following steps:

1. Call the searchdata_start endpoint 
   • This initiates the query to the database with your desired table and data fields
   • Returns a query ID, which will be used in Step 2
2. Call the searchdata_check endpoint 
   • Uses the query ID from Step 1 as an input
   • Once the query is done running on the backend, this endpoint returns a URL to a CSV file
3. Download the CSV file
    

Step 1: Call the searchdata_start endpoint

This step initiates the query against the database and returns a queryID, which will be used in Step 2. 
 

Example Request (returns query ID that will be used in the next step)

curl -X POST \ 
 --url 'https://l2l-swgdata.l2l.com/api/2.0/swgdata/searchdata_start/' \ 
 -H 'Authorization: Bearer {authentication_token}'\ 
 -H 'Accept: application/json'\ 
 -H 'Content-Type: application/json' \ 
 --data-raw '{ 
 "query_string": "[workspace_name] [guide_title]", 
 "logical_table_identifier": "content"
}'

Example Response

{
    "success": true,
    "data": {
        "queryid": "4a1b9817-3bce-4ecd-9540-34c3ad97d446"
    }
}

Components of a Call Request (searchdata_start endpoint)

Endpoint URL

https://l2l-swgdata.l2l.com/api/2.0/swgdata/searchdata_start/

Request Headers

Each API call must include the following headers.

Request Body

Each API call must include the following body elements.

Step 2: Call the searchdata_check endpoint

This step checks the query and returns a URL to a CSV file with your query results once the query is complete. 
 

Example Request

curl -X POST \ 
 --url 'https://l2l-swgdata.l2l.com/api/2.0/swgdata/searchdata_check/' \ 
 -H 'Authorization: Bearer {authentication_token}'\ 
 -H 'Accept: application/json'\ 
 -H 'Content-Type: application/json' \ 
 --data-raw '{ 
"queryid": "4a1b9817-3bce-4ecd-9540-34c3ad97d446"
}'

Note: If the query against the database is still running and not yet available, you will receive an error message. You can repeat the call to the seachdata_check endpoint again until the query results are available.  

Example Response (if query has successfully completed)

{
    "success": true,
    "data": {
        "results_url": "https://l2l-datalake-master.s3.amazonaws.com..."
    }
}

Example Response (if query is still running)

{
    "success": false,
    "error": "Query running"
}

Components of a Call Request (searchdata_check endpoint)

Endpoint URL

https://l2l-swgdata.l2l.com/api/2.0/swgdata/searchdata_check/

Request Headers

Each API call must include the following headers.

Request Body

Each API call must include the following body elements.

Step 3: Download the CSV file

The response of Step 2 is a URL pointing to a CSV file with your query results. By opening this link the CSV file is automatically downloaded. This allows for easily working with the data programatically. 

Synchronous Version of Data API

This version only consists of one step and returns a JSON response with the data requested. 

Call the searchdata endpoint

This step initiates the query against the database and returns a JSON response with your requested data. 
 

Example Request

curl -X POST \ 
 --url 'https://l2l-swgdata.l2l.com/api/2.0/swgdata/searchdata/' \ 
 -H 'Authorization: Bearer {authentication_token}'\ 
 -H 'Accept: application/json'\ 
 -H 'Content-Type: application/json' \ 
 --data-raw '{ 
 "query_string": "[workspace_name] [guide_title]", 
 "logical_table_identifier": "content", 
 "record_offset": 0, 
 "record_size": 10 
}'

Example Response

{ 
   "contents": [ 
       { 
           "available_data_row_count": 2, 
           "column_names": [ 
               "key1", 
               "key2" 
           ], 
           "data_rows": [ 
               [ 
                   "value1", 
                   "value2" 
               ], 
               [ 
                   "value1", 
                   "value2" 
               ] 
           ], 
           "record_offset": 0, 
           "record_size": 10, 
           "returned_data_row_count": 2, 
           "sampling_ratio": 1 
       } 
   ] 
}

Components of a Call Request (searchdata endpoint)

Endpoint URL

https://l2l-swgdata.l2l.com/api/2.0/swgdata/searchdata/

Request Headers

Each API call must include the following headers.

Request Body

Each API call must include the following body elements.

Construct your “query_string”

Data Columns

Column names being queried must be enclosed in square brackets [ ] and separated by a space. 

For example, in the query to retrieve all workspace names and guide titles in those workspaces, a valid query_string for the API is:

[workspace_name] [guide_title]

This would result in a list of all Workspace Names and all of the Guide Titles found within those workspaces and is equivalent to the following SQL query:

SELECT "workspace_name", "guide_title" FROM table

Example Request 

Note that this example is for the synchronous version, but the query string is the same for the Async version.

curl -X POST \ 
 --url 'https://l2l-swgdata.l2l.com/api/2.0/swgdata/searchdata/' \ 
 -H 'Authorization: Bearer {authentication_token}'\ 
 -H 'Accept: application/json'\ 
 -H 'Content-Type: application/json' \ 
 --data-raw '{ 
 "query_string": "[workspace_name] [guide_title]", 
 "logical_table_identifier": "content", 
 "record_offset": 0, 
 "record_size": 10 
}'

Example Response 

{ 
   "contents": [ 
       { 
           "available_data_row_count": 3, 
           "column_names": [ 
               "workspace_name", 
               "guide_title" 
           ], 
           "data_rows": [ 
               [ 
                   "Amsterdam", 
                   "Welding - Torch Training" 
               ], 
               [ 
                   "Amsterdam", 
                   "Line 1 - Sieve" 
               ], 
               [ 
                   "Boston", 
                   "Welding - Torch Training" 
               ] 
           ], 
           "record_offset": 0, 
           "record_size": 10, 
           "returned_data_row_count": 3, 
           "sampling_ratio": 1 
       } 
   ] 
}

Filter Response

The REST API supports various operators such as =, !=, >, >=, <=, <, contains, not contains.

For example, in a query to retrieve all guide titles and instructions titles from the ‘Amsterdam’ workspace, a valid query_string for the API is:

[guide_title] [instruction_title] [workspace_name] = 'Amsterdam'

Alternatively with the filter at front of query:

[workspace_name] = 'Amsterdam' [guide_title] [instruction_title]

When filtering by date, the filter format should be ‘MM/DD/YYYY’

[guide_created_at] >= '06/18/2023' [guide_title] [instruction_title]

Combine filters by separating by a space:

[workspace_name] = 'Amsterdam' [guide_created_at] >= '06/18/2023' [guide_title] [instruction_title]

Sort Response

The REST API supports sorting of the response by placing a "sort by" clause at the end of the query_string. This can be especially useful when parsing through paginated results (see Response Pagination). 

For example, in a query to retrieve all workspace names and IDs, sorted by workspace name, a valid query_string for the API is:

[workspace_name] [workspace_id] sort by [workspace_name]

Note that the "sort by" clause must be placed to the end of the query_string. Also note that the fields in the "sorted by" clause must also be included in the main part of your query_string. 

The query can also be sorted by multiple fields as in the following example:

[workspace_name] [workspace_id] sort by [workspace_name] [workspace_id]

Response Pagination

Note: This is primarily relevant for the synchronous version of the Data API due to the smaller row limit. 

When you make REST API calls, the APIs may return many rows of data in response. You can paginate the JSON response and retain the order of data across all pages. Given the ability to paginate, you can quickly populate tables and make new REST calls every time you go to the next page of the data on the table. There can be significant load time if you want to populate the data table with many rows (greater than 1000).

Note: The REST API has a limit of 100,000 rows per response, so queries that result in more rows will return truncated results. Pagination allows you to programmatically address this.

Paginated queries must be sorted to ensure consistent query behavior. The following query gives all values for [guide_title] and [guide_created_at] sorted by [guide_created_at] and filtered on [guide_created_at] >= '06/18/2023':

[guide_title] [guide_created_at] [guide_created_at] >= '06/18/2023' sort by [guide_created_at]

For some data sources, a field called [pagination_timestamp] is available to help you retrieve only the most recently updated or added rows. This is calculated on the finest level of detail in the underlying table, so it is most useful when querying at that level of granularity, as in when copying bulk data to a data warehouse.

To paginate results in your API response, adjust the following body components in the query:

The following call retrieves all values of [step_text], [step_id], and [step_updated_at], sorted by [step_updated_at]. The record_size value limits the response to 10 rows and the record_offset value skips to the 870th record in the underlying sorted data.

curl -X POST \ 
 --url 'https://l2l-swgdata.l2l.com/api/2.0/swgdata/searchdata/' \ 
 -H 'Authorization: Bearer {access_token}'\ 
 -H 'Accept: application/json'\ 
 -H 'Content-Type: application/json' \ 
 --data-raw '{ 
 "query_string": "[step_text] [step_id] [step_updated_at] sort by [step_updated_at]", 
 "logical_table_identifier": "content", 
 "record_offset": 870, 
 "record_size": 10 
}'

Data Sources

Below are the available data sources that can be accessed via the API. Each has a logical_table_identifier that is used when retrieving data.

You can find the details on data field availability and descriptions per source in our Data Glossary.

Content

• logical_table_identifier: content
• Alternative logical_table_identifier GUID: 2cb84f36-fc25-4fd0-8f71-2a8d2e65089f 
• Contains data regarding instructional content that is created in SwipeGuide

Events

• logical_table_identifier: events
• Alternative logical_table_identifier GUID: ebe1aaf3-eb0f-4c23-a743-b3364a78bf33
• Contains data regarding page view events of the content

Checklists

• logical_table_identifier: checklist_results
• Alternative logical_table_identifier GUID: f727b950-03cd-439f-989d-bc8c5a9a45ba
• Contains checklist submission results and the content they are tied to

Sign-offs

• logical_table_identifier: signoff_results
• Alternative logical_table_identifier GUID: dc8cc054-42a2-4258-b363-5017f99326c9
• Contains sign-off responses and the content they are tied to

Feedbacks

• logical_table_identifier: feedback
• Alternative logical_table_identifier GUID: ec0d1566-e255-4d90-9f21-e40c4d0a0cff
• Contains content content feedback submitted by viewers

Tags

• logical_table_identifier: tags
• Alternative logical_table_identifier GUID: 8fc7d097-b7df-41d7-bccb-9abe44387a0c
• Contains content tags

Users & Teams

• logical_table_identifier: users_and_teams
• Alternative logical_table_identifier GUID: 22482696-5234-44cd-aae8-835c586a4919
• Contains users and their associated teams and workspaces

Smart Skills

• logical_table_identifier: smart_skills
• Alternative logical_table_identifier GUID: 069b4334-d566-4e70-ac05-301f3f274a72
• Contains data regarding smart skills content and user skill status