Getting started. Version 2.0

Check out the demo to see Ingenia in action.

Look at the FAQ for any questions.

Go through the documentation and choose if you want to use Ingenia by the API or with one of the libraries.

Contact us to get your API key or if you have any questions.

If you would like to verify your API key or code data path then use the status call.

Ruby API library

https://github.com/ingenia-api/ingenia_ruby

Rate limiting

Ingenia by default limits a user to 4 calls per second, for every type of API call. Contact us to have this limit increased or removed if needed.

Endpoint

All calls are made with the following end point

api.ingeniapi.com/v2/

Both HTTP and HTTPS are supported as protocols. JSON is the data encapsulation format

Basic response format

All responses from the API gateway have the following format

Fields

Name Type Description
version string The version of the API that is responding
Example

"2.0"

data object The data payload response from the call
status string "okay" if the call is processed correctly, otherwise will be "error"
message string Message text describing nature of error. Only returned if an error occurred

 

Data structures

Item create / update input

An item is a block of text to which you can associate tags

Fields

Name Type Description
id string A unique text/numeric id. You can use your own, or have Ingenia generate one for you
Example

785uU423aC

text string Your item's content. [1]
url string Source URL to pull text from. [1]
Example

http://example.com

bundle_id integer ID of bundle to put item into
Example

45798

tags array The name of tags you wish applied to this item. Tags will be looked for first, then created if they do not exist. [2]
Example

[ "startups", "saas", "marketing" ]

tag_ids array The Ingenia IDs of the tags you want to have associated with this item. [2]
Example

[ 45, 787, 23 ]

tag_sets hash Groups of tags that you consider of the same type; tags will be returned as belonging to a tag set. [2]
Example

{ "topics": [ "startups", "saas", "marketing" ], "geography": [ "united kingdom" ] }

Notes

[1] You can input content as ONE of: text, a URL, a file (formats supported include txt, html, pdf, all the MS Office formats). If you send a URL, Ingenia will extract the most meaningful text from it, e.g., ignoring links. If you send a file, it will extract the text from it.

The text and the URL are input as part of the JSON component. The file is sent as a multipart encoded http field.

[2] Only specify one of the following: tags, tag_ids or tag_sets

Example

  {
    text: "High tech startups and their positive power to change for the good",
    tag_sets: {
      "Business": [ "startups", "business" ],
      "Economics": [ "technology"],
      "Mood": [ "positive" ]
    }
  }
  

Item show output

Fields

Name Type Description
id string A unique text/numeric id. You can use your own, or have Ingenia generate one for you
Example

785uU423aC

text string Your item's textual content
created_at date_time When this item was created
Example

2013-12-16T11:24:52+00:00

updated_at date_time When this item was last updated
Example

2013-12-16T11:25:52+00:00

last_classified_at date_time When this item was last classified by the system, or null if it hasn't been classified yet
Example

2013-12-16T11:25:52+00:00

Example

  {
    "id":"e19e134d0e79153349ff78a674283e0b",
    "last_classified_at":2013-12-16T11:25:07+00:00,
    "text":"How to get to scale with a saas startup in the UK? etc",
    "tag_sets":
      [
        {
          "topics":
          {
            "id":156,
            "tags":
              [
                {
                  "id":4352,
                  "name":"startups",
                  "score":"0.8",
                  "user_selected": "f"
                },
                {
                  "id":7811,
                  "name":"saas",
                  "score":"0.45",
                  "user_selected": "t"
                },
                {
                  "id":1327,
                  "name":"marketing",
                  "user_selected": "t"
                }
              ]
          }
        },
        {
          "geography":
          {
            "id":622,
            "tags":
              [
                {
                  "id":3321,
                  "name":"united kingdom",
                  "score":"0.37",
                  "user_selected": "f"
                }
              ]
          }
        }
      ]
    "created_at":"2013-12-16T11:24:52+00:00",
    "updated_at":"2013-12-16T11:24:56+00:00"
  }

Bundle create / update input

A collection of items related to each other

Fields

Name Type Description
name string The name of your bundle
tag_set_ids array An array of tag set IDs to be applied to this bundle. The tags in these tag sets will be available to the items in the bundle. If an existing bundle already has tag sets, then these can be removed by omitting the ID in the call.

Example

  {
    "name":"Tech Startups",
    "tag_set_ids": [ 232, 332, 6582 ]
  }

Bundle show output

A collection of items related to each other

Fields

Name Type Description
name string The name of your bundle
tag_sets array The tag sets that are currently attached to this bundle. Items within the bundle can use all the tags in these tag sets.

Example

  {
    "id":47858,
    "name":"Tech Startups",
    "tag_sets": [
      { "name": "technology", "id": 14562 },
      { "name": "business", "id": 666 }
    ]
    "created_at":"2014-03-13T15:36:51Z",
    "updated_at":"2014-03-13T15:36:51Z",
  }

Tag create / update input

Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc.

Fields

Name Type Description
name string The name of your tag
tag_set_id integer The ID of the tag_set to which this tag belongs
Example

3787

description string A description of this tag
disposition float The disposition of the tag. Float value between 0 and 1, defaults to 0.5. Lower values will tend to privilege precision (we suggest 0.25); higher values will tend to privilege recall (we suggest 0.75). For most uses, the default value will work well. You will want to privilege precision (with a disposition < 0.5) if you want each tag assignment to be accurate, and are less worried about some items being missed, i.e., you prefer to have false negatives than false positives. If the disposition is 0, no item will be tagged with this tag. You will want to privilege recall (with a disposition > 0.5) if you want each tag assignment to occur, and are less worried about some items being tagged incorrectly, i.e., you prefer to have false positives than false negatives. If the disposition is 1, all items will be tagged with this tag.
Example

0.75

Example

  {
    "name":"Text Analytics",
    "tag_set_id":37874,
    "description":"",
    "disposition": 0.3
  }

Tag show output

Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc.

Fields

Name Type Description
name string The name of your tag
tag_set_id integer The ID of the tag_set to which this tag belongs
Example

3787

confidence float Higher if Ingenia understands this tag; from 0 to 1
consistency float Higher if the tag has been applied to items that are very similar to one another; from 0 to 1
description string A description of this tag
disposition float The disposition of the tag. Float value between 0 and 1, defaults to 0.5. Lower values will tend to privilege precision (we suggest 0.25); higher values will tend to privilege recall (we suggest 0.75). For most uses, the default value will work well. You will want to privilege precision (with a disposition < 0.5) if you want each tag assignment to be accurate, and are less worried about some items being missed, i.e., you prefer to have false negatives than false positives. If the disposition is 0, no item will be tagged with this tag. You will want to privilege recall (with a disposition > 0.5) if you want each tag assignment to occur, and are less worried about some items being tagged incorrectly, i.e., you prefer to have false positives than false negatives. If the disposition is 1, all items will be tagged with this tag.
Example

0.75

Example

  {
    "id":554273,
    "name":"Text Analytics",
    "tag_set_id":8547,
    "confidence":0.95,
    "consistency":0.92,
    "description":"",
    "created_at":"2014-03-13T12:59:32Z",
    "updated_at":"2014-03-13T12:59:32Z"
  }

Tag set create / update input

A collection of thematically consistent tags

Fields

Name Type Description
name string The name of your tag set

Example

  {
    "name":"Big Data"
  }

Tag set show output

A collection of thematically consistent tags

Fields

Name Type Description
name string The name of your tag set

Example

  {
    "id":178751,
    "name":"Big Data",
    "created_at":"2014-03-12T12:17:33Z",
    "updated_at":"2014-03-12T12:17:33Z"
  }

Similarity response

An array of item matches to the similarity call

Fields

Name Type Description
id string The ID of the item. (either created by user or generated by the system)
text string Text of item, only first 50 characters
mode string Is either tag or word.
similarity float Score of similarity to source. 0=low, 1=high

Example

  {
    [
      { "item": { "id":12182, "text": "The fall in the rand has given wealthy Russians a new location to search for luxury..." }, "mode": "tag", "similarity": 0.62144 },
      { "item": { "id":9293, "text": "Robots tend to do jobs that no one wants to do. I am old enough to remember..."  }, "mode": "tag", "similarity": 0.62174 },
      { "item": { "id":25333, "text": "The market for RMB credit raised outside China has gone four weeks without a..." }, "mode": "word", "similariy": 0.62174 }
    ]
  }

 

API calls

The Ingenia API allows developers to create, retrieve, update, and delete all resources.

Classifications

Classify
Path
POST api.ingeniapi.com/v2/classify
Parameters
Name Type Description
min_tags integer Return at least these many tags
Default

0

max_tags integer Return at most these many tags
text string The text you want Ingenia to classify. [1]
Example

A comparative study of European secondary education systems illustrated issues related to their budgetary sustainability...

url string Source URL to read text from and classify from. [1]
Example

http://example.com

file multipart Source document sent as multi-part form submission. [1]
Example

document.pdf

Notes

[1] You can input content as ONE of: text, a URL, a file (formats supported include txt, html, pdf, all the MS Office formats). If you send a URL, Ingenia will extract the most meaningful text from it, e.g., ignoring links. If you send a file, it will extract the text from it.

Recommendation engine

Similar to text
Path
POST api.ingeniapi.com/v2/similar_to_text
Parameters
Name Type Description
text string Text to use as a starting point
limit integer Maximum number of items to return
Default

10

full_text integer Return full text of item on Ingenia
Default

1

mode string Using this field it is possible to constrain mathces to just "tags", "words" or "auto" (both tags and words).
Default

auto

Example

mode=tags

Response

See Similarity response

Similar to tags
Path
GET api.ingeniapi.com/v2/similar_to_tags
Parameters
Name Type Description
tag_ids array JSON encoded array of tag IDs to use as starting point
limit integer Maximum number of items to return
Default

10

full_text integer Return full text of item on Ingenia
Default

1

Response

See Similarity response

Summarisation

Summarise
Path
POST api.ingeniapi.com/v2/summarise
Parameters
Name Type Description
text string text to summarise
include_tags boolean If true the results be organised by tag, if false they are returned as a list
Default

true

max_sentences integer Maximum number of sentences to return
Default

2

order_by_position boolean If true, the results will be ordered as they appear in the text, if false, they will be ordered by score.
Default

false

Items

Blocks of textual content, typically self-contained and homogeneous
Index
Path
GET api.ingeniapi.com/v2/items
Description
Returns a list of all your items
Parameters
Name Type Description
limit integer Return these many results
Default

50

full_text boolean Show the results with all their text, however long
offset integer Offset the results I receive by this amount
Default

0

Show
Path
GET api.ingeniapi.com/v2/items/:id
Description
Returns a single item
Parameters
Name Type Description
id required string The ID of the item you want to show
Example

3casjghd67

full_text boolean Show the results with all their text, however long

Response

See Item show output

Create
Path
POST api.ingeniapi.com/v2/items
Description
Creates a new item
Parameters
Name Type Description
update_existing boolean Choice of what to do if the text sent via a create call already exists on Ingenia. If true, the tags supplied will overwrite those on the existing item (default). If false, no data is modified and a response is returned with a 409 code (Conflict) together with the existing item as JSON.
Default

true

classify boolean If true, the response will also include a classification.
file multipart File to be used as text source. Sent as multipart upload. Accepted file extensions are; Text (txt), Postscript Document Format (pdf) and Microsoft Office Documents (doc, docx, xlsx, ppt, pptx). [1]
json An item is a block of text to which you can associate tags
Notes

[1] You can input content as ONE of: text, a URL, a file (formats supported include txt, html, pdf, all the MS Office formats). If you send a URL, Ingenia will extract the most meaningful text from it, e.g., ignoring links. If you send a file, it will extract the text from it.

The text and the URL are input as part of the JSON component. The file is sent as a multipart encoded http field.

Update
Path
PUT api.ingeniapi.com/v2/items/:id
Description
Update an existing item
Parameters
Name Type Description
id required string The ID of the item you want to update.
Example

3casjghd67

file multipart File to be used as text source. Sent as multipart upload. Accepted file types are: Text (txt), Postscript Document Format (pdf), Microsoft Office Documents (doc, docx, xls, xlsx, ppt, pptx). [1]
json An item is a block of text to which you can associate tags
Notes

[1] You can input content as ONE of: text, a URL, a file (formats supported include txt, html, pdf, all the MS Office formats). If you send a URL, Ingenia will extract the most meaningful text from it, e.g., ignoring links. If you send a file, it will extract the text from it.

The text and the URL are input as part of the JSON component. The file is sent as a multipart encoded http field.

Delete
Path
DELETE api.ingeniapi.com/v2/items/:id
Description
Delete an existing item
Parameters
Name Type Description
id required string The ID of the item you want to delete.
Example

3casjghd67

Similar to
Path
GET api.ingeniapi.com/v2/items/:id/similar_to
Parameters
Name Type Description
id required string ID of item to get similar items to
Example

3casjghd67

mode string Using this field it is possible to constrain mathces to just "tags", "words" or "auto" (both tags and words).
Default

auto

Example

mode=tags

Response

See Similarity response

Bundles

Groups of thematically consistent items
Index
Path
GET api.ingeniapi.com/v2/bundles
Description
Returns a list of all your bundles
Parameters
Name Type Description
limit integer Return these many results
Default

50

offset integer Offset the results I receive by this amount
Default

0

Show
Path
GET api.ingeniapi.com/v2/bundles/:id
Description
Returns a single bundle
Parameters
Name Type Description
id required integer The ID of the bundle you want to show
Example

2314

Response

See Bundle show output

Find_by_name
Path
GET api.ingeniapi.com/v2/bundles/find_by_name
Description
Looks for a bundle that matches text input
Parameters
Name Type Description
text string Text of bundle to look for
Example

"Tech Startups"

Create
Path
POST api.ingeniapi.com/v2/bundles
Description
Creates a new bundle
Parameters
Name Type Description
json A collection of items related to each other
Update
Path
PUT api.ingeniapi.com/v2/bundles/:id
Description
Update an existing bundle
Parameters
Name Type Description
id required integer The ID of the bundle you want to update.
Example

5611

json A collection of items related to each other
Delete
Path
DELETE api.ingeniapi.com/v2/bundles/:id
Description
Delete an existing bundle
Parameters
Name Type Description
id required string The ID of the bundle you want to delete.
Example

gqj78219nc

Tags

Tags are meaningful words or expressions that you want to associate to some of your items
Index
Path
GET api.ingeniapi.com/v2/tags
Description
List all your tags
Parameters
Name Type Description
limit integer Return these many results
Default

50

offset integer Offset the results I receive by this amount
Default

0

Show
Path
GET api.ingeniapi.com/v2/tags/:id
Description
View a single tag
Parameters
Name Type Description
id required integer The ID of the tag you want to show
Example

42

Response

See Tag show output

Find_by_name
Path
GET api.ingeniapi.com/v2/tags/find_by_name
Description
Looks for a tag that matches text input
Parameters
Name Type Description
text string Text of tag to look for
Example

"Tech Startups"

Create
Path
POST api.ingeniapi.com/v2/tags
Description
Create a new tag
Parameters
Name Type Description
json Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc.
Update
Path
PUT api.ingeniapi.com/v2/tags/:id
Description
Update an existing tag
Parameters
Name Type Description
id required integer The ID of the tag you want to update
Example

42

json Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc.
Merge
Path
PUT api.ingeniapi.com/v2/tags/:id
Description
Merge two or more existing tags
Parameters
Name Type Description
id required integer The ID of the tag into which you want to merge other tags; the resulting tag will have this name
Example

42

tag_ids required integer An array of tag IDs that will be merged into the main tag
Example

[ 23, 43, 2113 ]

Delete
Path
DELETE api.ingeniapi.com/v2/tags/:id
Description
Delete an existing tag
Parameters
Name Type Description
id required integer The ID of the tag you want to delete
Example

42

Tag sets

Tag sets are thematically consistent groups of tags, such as, say, world countries, business sectors, product types, companies, concepts, topics, etc
Index
Path
GET api.ingeniapi.com/v2/tag_sets
Description
List all your tag sets
Parameters
Name Type Description
limit integer Return these many results
Default

50

offset integer Offset the results I receive by this amount
Default

0

Show
Path
GET api.ingeniapi.com/v2/tag_sets/:id
Description
View a single tag set
Parameters
Name Type Description
id required integer The ID of the tag set you want to show
Example

412

Response

See Tag set show output

Find_by_name
Path
GET api.ingeniapi.com/v2/tag sets/find_by_name
Description
Looks for a tag set that matches text input
Parameters
Name Type Description
text string Text of tag set to look for
Example

"Tech Startups"

Create
Path
POST api.ingeniapi.com/v2/tag_sets
Description
Create a new tag set
Parameters
Name Type Description
json A collection of thematically consistent tags
Update
Path
PUT api.ingeniapi.com/v2/tag_sets/:id
Description
Update an existing tag set
Parameters
Name Type Description
id required integer The ID of the tag set you want to update
Example

412

json A collection of thematically consistent tags
Merge
Path
PUT api.ingeniapi.com/v2/tag_sets/:id
Description
Merge two or more existing tag sets
Parameters
Name Type Description
id required integer The ID of the tag set into which you want to merge the other tag sets; the resulting tag set will have this name
Example

412

tag_set_ids required integer JSON encoded tag set IDs to merge into request tag set
Example

[ 12, 34, 56 ]

Delete
Path
DELETE api.ingeniapi.com/v2/tag_sets/:id
Description
Delete an existing tag set
Parameters
Name Type Description
id required integer The ID of the tag set you want to delete.
Example

412

Administrative Calls

Status
Path
GET api.ingeniapi.com/v2/status
Description
Use this to test your API key, see [status call] for details
Parameters
Name Type Description
total_bundles integer Number of bundles you have created
Example

64

total_items integer Number of items you have created
Example

1554

processed_items integer Number of items Ingenia has processed
Example

1554

total_tag_sets integer Number of tag sets you have created
Example

2

processed_tag_sets integer Number of tag sets Ingenia has processed
Example

2

total_tags integer Number of tags you have created
Example

167

processed_tags integer Number of tags Ingenia has processed
Example

167

ready_to_classify boolean It will be true if all your data has been processed
Example

true

Clear_data
Path
POST api.ingeniapi.com/v2/clear_data
Description
View a single tag set
Parameters
Name Type Description
item_count integer Number of items you have that are about to be deleted
Example

123

tag_set_count integer Number of tag sets you have that are about to be deleted
Example

4

tag_count integer Number of tags you have that are about to be deleted
Example

6502