Support

Dandelion API User-defined spots

Sometimes you may find yourself in need of extending our internal knowledge graph, perhaps because of some domain-specific terminology you want Dandelion API to be able to recognize. If this is the case, User-defined spots may help you!

With User-defined spots you can extend the internal knowledge graph by providing new terms to match against its entities, or boosting the already provided ones. Developing a mobile app that involves much slang? Define a set of custom-spots and use them in all the Entity Extraction API methods!

Dandelion API provides a handy endpoint for managing all your custom spot sets, following the CRUD(L) paradigm. Once you defined your own spots, enable them by using the dedicated custom_spots parameter available in most of the Entity Extraction APIs.

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)"
    }
  ]
}

Spot objects support the following fields:

spot required
The actual spot that can be found in the text and you want to be linked to a topic.
Type string
topic required
The topic the spot should be linked to. Topics are represented as wikipedia pages; you can refer to each topic by its URI http://en.wikipedia.org/wiki/Baseball, its title Baseball or its wikipedia page ID 3850. In this two last cases, the lang attribute will be used to select the Wikipedia to match against. To see a concrete example, check out the Example section.
Type string
greedy optional
Greedy spots will always be linked to their topic when found in the text, regardless of their semantic relatedness with the context. This feature can be useful in some very-contextualized environments, where there can't be ambiguity for certain spots.
Type boolean
Default value false
exactMatch optional
User-defined spots are usually "relaxed", which means that they can be used even if the text doesn't match at 100%; for example, the spot Pussy Riot by default would match also pussy-riot. Sometimes however this is not a desired behaviour: a spot A* for the famous A* search algorithm for example may lead to interesting results ;). In this case setting exactMatch to true would solve the problem.
Type boolean
Default value false

Endpoint

https://api.dandelion.eu/datatxt/custom-spots/v1

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

Methods

Create new custom spots

POST https://api.dandelion.eu/datatxt/custom-spots/v1
parameters
data required
The set of spots you want to create, structured as described above.
response
{
  "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": "..."
      }
    ]
  }
}
example
curl -i --data-urlencode "data@spots.json" -d "token=<YOUR_TOKEN>"   http://api.dandelion.eu/datatxt/custom-spots/v1

This example assumes that you wrote your spots in a file named spots.json

Read a specific spots set

GET https://api.dandelion.eu/datatxt/custom-spots/v1?id=<spots-id>
parameters
id required
The id of the spots you want to fetch.
response
Return the requested spots, see example
example
curl -i http://api.dandelion.eu/datatxt/custom-spots/v1?token=<YOUR_TOKEN>&id=<SPOTS_ID>

Update existing spots

PUT https://api.dandelion.eu/datatxt/custom-spots/v1?id=<spots-id>&data=<the-json>
parameters
id required
The id of the spots you want to update.
data required
The updated spots, structured as described above.
response
{
  "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": "..."
      }
    ]
  }
}
example
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

This example assumes that you wrote your spots in a file named spots.json

Delete spots

DELETE https://api.dandelion.eu/datatxt/custom-spots/v1?id=<spots-id>
parameters
id required
The id of the spots you want to delete.
example
curl -i -X DELETE http://api.dandelion.eu/datatxt/custom-spots/v1?token=<YOUR_TOKEN>\&id=<SPOTS_ID>

List all your spots

GET https://api.dandelion.eu/datatxt/custom-spots/v1
response
{
  "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": [
              "...": "..."
          ]
      }
    }
  ]
}
example
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.

SpazioDati Via A. Olivetti 13, 38122, Trento (TN) -


Dandelion API built with by

site privacy | api privacy | tos | cookies

Contact Us

@dandelionapi

Need more info or a custom project? Write us: hello@dandelion.eu

About Us

We're a startup based in Italy, specialized in Semantics & Big Data.
Find out more about us at spaziodati.eu