Page Comparison

This is a basic tutorial for using the Gavagai Explorer This is a basic tutorial for using the Gavagai Explorer API.

We recommend that you get familiar with using Gavagai Explorer before you start developing with the API. Make sure that you understand the basics, such as creating projects and uploading texts, exploring and refining your project, or creating reports and applying models. All functionality in Gavagai Explorer is built on this API, so you will have a much easier time understanding the different steps if you have already seen them in the Explorer web interface.

...

To help you with making calls to the API for testing purposes you may want to use an extension to your browser. We recommend Postman., we use Swagger UI as a Rest API Documentation tool, which allows you to easily interact with our API, through your browser. You can access the documentation for the Explorer API here. 

1. Get an account with Gavagai Explorer at explorer.gavagai.seio if you haven’t already done so. For using the Gavagai Explorer API, you will need your login credentials (email address and password).
2. Test that the account is setup and working properly by performing a call to the following method. 

   https://api.gavagai.se/explorer/v1/projects
   Curl example:
   curl -u username:password "https://api.gavagai.se/explorer/v1/projects"

3. This should give you the following response, as you haven’t created any projects yet (if you already did create some projects, you should get an overview):
   []

For support, you should consult the API documentation. If you need more support than that, you can request it from support@gavagai.seio Just send an email with any issues you might have and our support group will get back to you.

...

• JSON. For more information, click here and select "application/json" as the Request Body format.
• CSV or XLSX. You can learn more about the structure of these formats here.

...

For more information, you can check out the API documentation for /projects.

III. Exploring a project

...

You will also need to supply a ProjectExplorationContext containing several different properties that are needed for exploration. The context definition has to be supplied in JSON format. You can learn more about these formats here.

{
  "columnHeaderId" : 12345,
  "language" : "...",
  "topicsPageSize" : 12345,
  "associationsPageSize" : 12345,
  "ignoreTerms" : [ "...", "..." ],
  "filters" : [ {
    "value" : "...",
    "operator" : "NOT_EQUAL",
    "columnHeaderId" : 12345
  }, {
    "value" : "...",
    "operator" : "EQUALS",
    "columnHeaderId" : 12345
  } ],
  "groups" : [ {
    "title" : "...",
    "topics" : [ {
      "title" : "...",
      "terms" : [ "...", "..." ]
    }, {
      "title" : "...",
      "terms" : [ "...", "..." ]
    } ],
    "pinned" : true
  }, {
    "title" : "...",
    "topics" : [ {
      "title" : "...",
      "terms" : [ "...", "..." ]
    }, {
      "title" : "...",
      "terms" : [ "...", "..." ]
    } ],
    "pinned" : true
  } ],
  "acceptOverageToken" : "...",
  "conceptFilter" : {
    "inclusive" : true,
    "filtered" : true,
    "conceptId" : 12345
  }
}

Some of the attributes in the ProjectExplorationContext are optional, others are required. For this tutorial, we will set the attributes columnHeaderId, language, topicsPageSize, ignoreTerms, and groups (of which the first two are mandatory).

1. Perform a GET request to  https://api.gavagai.se/explorer/v1/projects. Look at the recently created project and note down the relevant attribute values from its headers array. We want to explore the header "review", so its id is the columnHeaderId needed. Here we can also note down the language (specified according to ISO 639-1) from the suggestedLanguage attribute in case we don't already know what language our texts are written in.Next is the topicsPageSize. This parameter affects the number of topics that will be retrieved in each exploration. By default, this number is 30, but let's say we want to see the top 40 topics this time. 
2. Let's assume we already know that "hotel" is not a very informative term for exploring hotel reviews (all the reviews should be about this particular hotel, after all). So we add it together with its morphological variant "hotels" to the list of ignoreTerms.
3. Finally, we want to specify a couple of topics and terms. These are always organised in groups, and each group has to contain at least one topic. Let's add one group called "staff" with a topic titled "staff" that contains the terms "staff", "the staff", "general staff", as well as the topic "manager", containing "manager" and "the manager". Add another group titled "stay" with a topic "stay" and the terms "stay", "stayed", and "staying". We also want to pin the groups ("pinned": true) to ensure they will be noticeable.
4. Our final ProjectExplorationContext will look like as follows:
   

   {
     "columnHeaderId" : your_id,
     "language" : "EN",
     "topicsPageSizelanguage" : 40"EN",
     "ignoreTerms" : [ "hotel", "hotels" ],
     "groups" : [ {
       "title" : "staff",
       "topics" : [ {
         "title" : "staff",
         "terms" : [ "staff", "the staff", "general staff" ]
       }, {
         "title" : "manager",
         "terms" : [ "manager", "the manager" ]
       } ],
       "pinned" : true
     }, {
       "title" : "stay",
       "topics" : [ {
         "title" : "stay",
         "terms" : [ "stay", "stayed", "staying" ]
       } ],
       "pinned" : true
     } ]
   }

5. Send a POST request to the /explore endpoint that contains your exploration context as body and "Content-Type: application/json;charset=UTF-8" as header.
   Curl example:
   curl -X POST -u username:password -H "Content-Type: application/json;charset=UTF-8" -d '{
  "columnHeaderId" : your_id,
  "language" : "EN",
  "topicsPageSize" : 40,
  "ignoreTerms" : [ "hotel", "hotels" ],
  "groups" : [ {
    "title" : "staff",
    "topics" : [ {
      "title" : "staff",
      "terms" : [ "staff", "the staff", "general staff" ]
    }, {
    "title" : "manager",
    "terms" : [ "manager", "the manager" ]
    } ],
    "pinned" : true
  }, {
    "title" : "stay",
    "topics" : [ {
       "title" : "stay",
       "terms" : [ "stay", "stayed", "staying" ]
     } ],
    "pinned" : true
  } ]
}' "https://api.gavagai.se/explorer/v1/projects/{id}/explore"

6. Now, check your project and see for yourself if your project was explored by sending a GET request to https://api.gavagai.se/explorer/v1/projects/{id}/explore.

For more information, you can check out the API documentation for projects/{id}/explore.

IV. Appending more texts to your project

...

• JSON. For more information, click here and select "application/json" as the Request Body format.
• CSV or XLSX. You can learn more about the structure of these formats here. Be aware that the file should be in the same format as the original file you used to create the project (i.e., it should have the same columns), but it should not contain a header row.

...

For more information, you can check out the API documentation for /append (form data) and /append (json). You can switch the Request Body format to "application/json" if you would like know more about the JSON Request.

V.

...

Insufficient Credtis

If your account does not have sufficient credits to explore a project, you will have to accept overage to be able to explore need to purchase additional credits before you an explore it (please be aware that this will result in a charge to your credit card). To accept overage (and charging your card)purchase credits, you will have to include perform an extra step when sending requests to the /explore endpoint (see 99385403 for exploring without accepting overage)prior to performing an exploration.

1. After creating your project (see 99385403), send a GET request to https://api.gavagai.se/explorer/v1/projects/{id}/explore and note the status message and state which should say "Not started" / "NOT_STARTED".
2. Send a POST request to https://api.gavagai.se/explorer/v1/projects/{id}/explore, as you did in 99385403.
3. Send a GET request to the same endpoint to see if the project was explored or not. The response will look something like this:
   {
  "status": {
    "startTime": 0,
    "progress": 100,
    "message": "No credits left. Accept with overage tokenYou need to buy more credits",
    "state": "NO_CREDITS",
    "acceptOverageToken": "1101e4df-e80b-4cbc-s79a-cd3d9af61511",
      "overageAmount": 213,
    "productPriceInCents": 81,
    "currency": "SEK"
  },
  "groups": [],
  "ignoreTerms": [
    "hotels",
    "hotel"
  ],
  "language": "EN",
  "columnHeaderId": 70075,
  "filters": [],
  "tones": [
    "NEGATIVITY",
    "POSITIVITY",
    "POSITIVITY",
    "SKEPTICISM"
  ],
  "totalDocumentCount": 0
}
   As you can see, the status message and code should now say "No credits left. Accept with overage token" and "NO_CREDITS" respectively. You will also see that the acceptOverageToken now has a value, and you have some additional information about the overage amount in the overageAmount, productPriceInCents, andcurrency fields. If you are okay with the amount, note down the acceptOverageToken and add it to the ProjectExplorationContext. Then, send
       "SKEPTICISM"
  ],
  "totalDocumentCount": 0
}
   
4. As you can see, the status message and code should now say "No credits left. You need to buy more credits" and "NO_CREDITS" respectively. You will also see that the overageAmount now has a value, which corresponds to the additional credits you need to purchase.
5. You can purchase the credits using the Purchase Credits endpoint. You can either purchase the exact number of credits you need or a some extra credits - the credits will never expire.
   Curl example:
   curl -X POST -u username:password -H "Content-Type: application/json" -d "{\"quantity\": 213}" "https://api.gavagai.se/explorer/projects/account/credits
   
6. Once you have purchase additional credits,  send a POST request to the /explore endpoint with your updated the same ProjectExplorationContext as before.
7. Now, check your project again to see if your project was explored by sending a GET request to https://api.gavagai.se/explorer/v1/projects/{id}/explore.

   
   

...