Explorer API Common Use Cases
End-to-end upload data, create project, analyze, and retrieve report
- Create project
- Upload data in a file:
POST /projects - Or using JSON:
POST /projects - *Repeatedly check for Initialization to finish (project status should be “EXPLORABLE” when done):
GET /projects/{id}
- Upload data in a file:
- Explore (clustering)
- Start exploration:
POST /projects/{id}/explore - *Repeatedly check for exploration to finish (status should be 100%)
GET /projects/{id}/explore
- Start exploration:
- Create report
- Start report generation:
POST /projects/{id}/reports - *Wait for report to finish. Check the returned list for the report id and its status repeatedly until it’s done:
GET /projects/{id}/reports Retrieve the report:
- Start report generation:
End-to-end apply a model to a project
- Create project
- Upload data in a file:
POST /projects - Or using JSON:
POST /projects - *Repeatedly check for Initialization to finish (project should be “EXPLORABLE” when done:
GET /projects/{id}
- Upload data in a file:
- Explore (clustering) with a model:
- Get the details of a previously saved model
GET /models/{id} - Start exploration with the ignoreTerms and groups fields of the model retrieved in the previous step
POST /projects/{id}/explore - *Repeatedly check for exploration to finish (status should be 100%)
GET /projects/{id}/explore
- Get the details of a previously saved model
- Create report
- Start report generation:
POST /projects/{id}/reports - *Wait for report to finish. Check the returned list for the report id and its status repeatedly until it’s done:
GET /projects/{id}/reports - Retrieve the report:
GET /projects/{id}/reports/{reportId}
- Start report generation:
Get a topic and sentiment breakdown for texts in a project
- Create project and upload texts (as above)
- Apply a model (as above) or build topics in the GUI
- Return the relevant information
- Fetch a CellTopicInformation response:
GET /projects/{id}/result/cells
Get a topic and sentiment breakdown in export format (.csv or .xlsx)
- Create project and upload texts (as above)
- Apply a model (as above) or build topics in the GUI
- Retrieve topic ids for topics that should be analysed
- Fetch a ProjectExplorationResponse
GET /projects/{id}/explore - Then, it is a question of working with the JSON response to pluck out the topic ids
- Request a CSV_FULL or EXCEL report (as above).
- Make sure to pass as parameters the relevant topic ids for extra analysis
- See POST /projects/{id}/reports for full details of how to pass parameters
Get Tonality and/or Examples from a Topic or Group
- For a group
If the sentiment and examples for a topic have been calculated already (for your given combination of terms and associations) you could retrieve them with
GET /projects/{id}/explore/groups/{groupId}/tonalitiesIf the above call gives no result, you need to initiate the calculation:
POST /projects/{id}/explore/groups/{groupId}/tonalities- Repeatedly then poll until the calculation is done using the GET above
- For a topic in a group
- Similarly to the above, if the sentiment and examples were previously calculated just get them:
GET /projects/{id}/explore/groups/{groupId}/topics/{topicId}/tonalities - If the above call gives no result, you need to initiate the calculation:
POST /projects/{id}/explore/groups/{groupId}/topics/{topicId}/tonalities
- Repeatedly then poll until the calculation is done using the GET above
- Please note that for both the GET and POST requests, the topic identified by the topicId parameter must be contained within the group identified by the groupId parameter.
- Similarly to the above, if the sentiment and examples were previously calculated just get them:
Creating and applying a Dynamic model to another project
- Create a dynamic model from a project identified by the 'projectId_master' parameter by setting the 'dynamic' flag to true in the model create request body
POST /models/create?projectId={projectId_master}- Ensure that the relevant groups are pinned prior to saving the model.
- (Optional) Share the dynamic model to another user, using the share model request
POST /models/{id}/share- (Optional) Accept the invitation
PUT /models/invitations/{id}/accept
- (Optional) Accept the invitation
- Connect another project identified by 'projectId_dependent' to the dynamic model by setting the 'modelId' parameter to be the id of the dynamic model in the project update request body
PUT /projects/{projectId_dependent} - Update the structure of the dynamic model by updating the model connected to the project identified by 'projectId_master'
- The ignoreTermsDictionary and groups.topics.dictionary parameters are not relevant when updating the model connected to the project 'projectId_master'
PUT /projects/{projectId_master}/model - Ensure that the relevant groups are pinned prior to updating the model.
- The ignoreTermsDictionary and groups.topics.dictionary parameters are not relevant when updating the model connected to the project 'projectId_master'
- Explore the project identified by 'projectId_master' by using the standard exploration request.
- The 'ignoreTerms' and 'groups' parameters should not be specified if the project is connected to a dynamic model
POST /projects/{projectId_master}/explore
- The 'ignoreTerms' and 'groups' parameters should not be specified if the project is connected to a dynamic model
- Explore the project identified by 'projectId_dependent' to receive the latest version of the dynamic model (with translations, if the language of the dynamic model is different), using the standard exploration request
- Again, the 'ignoreTerms' and 'groups' parameters should not be specified if the project is connected to a dynamic model
POST /projects/{projectId_dependent}/explore
- Again, the 'ignoreTerms' and 'groups' parameters should not be specified if the project is connected to a dynamic model
- Retrieve the latest exploration results for the project identified by 'projectId_dependent' by using the standard GET exploration request
GET /projects/{projectId_dependent}/explore- If the language of the dependent project is different that the master project, the ignoreTermsDictionary and the groups.topics.dictionary parameters can be used to determine the translations of the ignore terms and topic terms
- The ignoreTermsDictionary is a map with form { 'translation': 'sourceTerm' } which can be used to identify the sourceTerm to which the values in the ignoreTerms correspond
- Similarly, the groups.topics.dictionary is a map with form { 'translation': 'sourceTerm' } which can be used to identify the sourceTerm to which the values in the terms correspond, within each topic
- Update the translations (if the language of the dynamic model is different) of the model connected to the project identified by 'projectId_dependent' by using the update model request
PUT /projects/{projectId_dependent}/model- Updating translations for ignore terms
- Update translations for the ignoreTerms by specifying the new translations in the ignoreTerms parameter
- Retain a link to the 'source terms' in the original language of the dynamic model by using the ignoreTermsDictionary parameter.
- The ignoreTermsDictionary is a map with form { 'translation': 'sourceTerm' }
- Multiple translations can be specified for the same sourceTerm
- For ignore terms, a translation is allowed to have a NULL sourceTerm, that is, a standalone ignore term is allowed to be added in the new language
- To remove all translations corresponding to a 'source term' in the new language, do not specify any entries in the dictionary with the value being the 'source term'
- Updating translations for the topic terms
- Update translations for topic terms by specifying the new translations in the terms parameter of the TopicInput object in the request.
- Retain a link to the 'source terms' in the original language of the dynamic model by using the dictionary parameter for the relevant topic
- The dictionary is a map with form { 'translation': 'sourceTerm' }
- Multiple translations can be specified for the same sourceTerm
- For topic terms, a translation is NOT allowed to have a NULL sourceTerm, that is, a standalone topic term is NOT allowed to be added in the new language
- To remove all translations corresponding to a 'source term' in the new language, do not specify any entries in the dictionary with the value being the 'source term'
- Updating translations for ignore terms
- Re-explore the project identified by 'projectId_dependent' to retrieve the exploration results with the updated translations
POST /projects/{projectId_dependent}/explore - Retrieve the latest exploration results to view the updated model as well as the changes that were made to the model
GET /projects/{projectId_dependent}/explore- The field modelChangeSet in the exploration response can be used to identify what changes were made to the model of the dependent project during the exploration.
- The changes specified in this field include
- Which topics were changed (ADDED, REMOVED, MODIFIED, RENAMED)
- Which terms were added to topics (with the translations, if applicable)
- Which terms were removed from topics (with the translations, if applicable)
- If there was a rename, what the new is and what the previous name was
- Which ignore terms were added to the model (with the translations, if applicable)
- Which ignore terms were removed from the model (with the translations, if applicable)
- Which topics were changed (ADDED, REMOVED, MODIFIED, RENAMED)
- The modelChangeSet field is only populated when there is an update to be made to the model of the dependent project due to a change in the dynamic model from the master project.