Dandelion API User-defined spots

Custom-Spot structure

You can group your own spots together and enable/disable them on each call to Entity Extraction API. A "set" of user-defined spots is simply represented as a list of Spot objects. The JSON that describes User-defined spots has the following structure:

{
  "lang": "The language of the spots",
  "description": "A human-readable string you can use to describe this set of spots",
  "list": [
    {
      "spot": "The new spot",
      "topic": "The entity linked to the spot",
      "greedy": "Is this spot greedy? (optional, see below)",
      "exactMatch": "Must this spot be an exact match? (optional, see below)"
    }
  ]
}

Endpoint

Depending on the HTTP method used to access this endpoint, a different functionality will be triggered.

Methods

{
  "id": "0123-abcd-45678901-cdefabcd",
  "created": "2014-03-02T00:04:16",
  "modified": "2014-03-02T00:04:16",
  "data": {
    "description": "My first spots",
    "lang": "it",
    "list": [
      {
        "spot": "làres",
        "topic": "Larix decidua"
      },
      {
        "spot": "...",
        "topic": "..."
      }
    ]
  }
}

curl -i --data-urlencode "data@spots.json" -d "token=<YOUR_TOKEN>"   http://api.dandelion.eu/datatxt/custom-spots/v1

curl -i http://api.dandelion.eu/datatxt/custom-spots/v1?token=<YOUR_TOKEN>&id=<SPOTS_ID>

{
  "id": "82cf5f938180d3d780b376bfff6",
  "created": "2014-03-02T00:04:16",
  "modified": "2014-03-03T10:10:16",
  "data": {
    "description": "My first spots",
    "lang": "it",
    "list": [
      {
        "spot": "làres",
        "topic": "Larix decidua"
      },
      {
        "spot": "...",
        "topic": "..."
      }
    ]
  }
}

curl -i -X PUT --data-urlencode "data@spots.json" -d "token=<YOUR_TOKEN>" -d "id=<SPOTS_ID>" http://api.dandelion.eu/datatxt/custom-spots/v1

curl -i -X DELETE http://api.dandelion.eu/datatxt/custom-spots/v1?token=<YOUR_TOKEN>\&id=<SPOTS_ID>

{
  "count": 2,
  "items": [
    {
      "id": "0123-abcd-45678901-cdefabcd",
      "created": "2015-10-21T16:29:37",
      "modified": "2015-10-21T16:29:37",
      "data": {
        "lang": "en",
        "description": "",
        "list": [
            "...": "..."
        ]
      }
    },
    {
      "id": "0123-abcd-45678901-cdefabce",
      "created": "2015-10-21T16:29:39",
      "modified": "2015-10-21T16:29:39",
      "data": {
          "lang": "it",
          "description": "",
          "list": [
              "...": "..."
          ]
      }
    }
  ]
}

curl -i http://api.dandelion.eu/datatxt/custom-spots/v1?token=<YOUR_TOKEN>

User-defined spots example

A very simple example to have an idea of what it means to define custom spots in Entity Extraction API. Here we want to add some common-names of plants from the dialect used in Trento (Italy). The plants each spot refers to are represented with the title of their Wikipedia pages.

{
    "description": "My botanical custom spots",
    "lang": "it",
    "list": [
        {
            "spot": "làres",
            "topic": "Larix decidua"
        },
        {
            "spot": "stropèr",
            "topic": "Salix viminalis"
        },
        {
            "spot": "noselèr",
            "topic": "Corylus avellana"
        },
        {
            "spot": "pomèr",
            "topic": "Malus domestica"
        },
        {
            "spot": "brugnèra",
            "topic": "Prunus domestica"
        }
    ]
}

After successfully submitting this JSON to the User-defined spots endpoint, we could use Entity Extraction API to annotate text from — for example — local botanical journals, or use Text Classification API to classify articles based on the type of plants they refer to.