NAV
cURL

Intro to YonderAPI v2

YonderAPI provides access to functionalities developed by Yonder. The following suite of text and image analysis API services can be composed together into a pipelines to solve a variety of problems and create smarter applications and services in different verticals.

Authentication

To use YonderAPI you need to first register at our website and get your credentials, i.e. YOUR_ACCESS_TOKEN. YonderAPI expects for the credentials assigned in the registration process to be included in all API requests to the server.

API on Text Documents

The following set of API allows for extracting semantic information from Text Documents. If you need to create a Text Collection, i.e. a repository of metadata coming from multiple texts useful for analyzing inter-documents relations (e.g. for measuring document similarities), please refer below to YonderAPI Text Collections.

Entity Extraction

Request example - POST fromURL...

curl --ssl-reqd --request POST --data url=https%3A%2F%2Fwww.theguardian.com%2Fworld%2F2016%2Fjul%2F22%2Fmissing-flight-mh370-hunt-for-debris-will-not-be-extended "https://api.yonderlabs.com/2.0/text/entityextraction/fromURL?limit=10&access_token=YOUR_ACCESS_TOKEN"

... and response body (200/JSON):

{
  "url": "https://www.theguardian.com/world/2016/jul/22/missing-flight-mh370-hunt-for-debris-will-not-be-extended", 
  "text": "The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...]", 
  "limit": 10, 
  "entities": [
    {
            "info": {
                "wikipedia": "Australia",
                "description": "country in the Southern hemisphere"
            },
            "score": 4.4,
            "type": "GPE",
            "name": "Australia"
        },
        {
            "info": {
                "wikipedia": "Malaysia",
                "description": "sovereign state in Southeast Asia"
            },
            "score": 4.01,
            "type": "GPE",
            "name": "Malaysia"
        },
        {
            "info": {
                "wikipedia": "China",
                "description": "sovereign state in East Asia"
            },
            "score": 3.6,
            "type": "GPE",
            "name": "China"
        },
        {
            "info": {
                "wikipedia": "Putrajaya",
                "description": "federal administrative centre of Malaysia"
            },
            "score": 1.83,
            "type": "GPE",
            "name": "Putrajaya"
        },
        {
            "info": {
                "wikipedia": null,
                "description": null
            },
            "score": 0.5,
            "type": "ORG",
            "name": "Malaysia Airlines"
        },
        {
            "info": {
                "wikipedia": null,
                "description": null
            },
            "score": 0.5,
            "type": "ORG",
            "name": "MH370"
        }
  ]
}

Request example - POST fromText...

curl --ssl-reqd --request POST --data text="The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...]." "https://api.yonderlabs.com/2.0/text/entityextraction/fromText?limit=10&access_token=YOUR_ACCESS_TOKEN"

... and response body (200/JSON):

{
  "url": null, 
  "text": "The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...].", 
  "limit": 10, 
    {
            "info": {
                "wikipedia": "Australia",
                "description": "country in the Southern hemisphere"
            },
            "score": 4.4,
            "type": "GPE",
            "name": "Australia"
        },
        {
            "info": {
                "wikipedia": "Malaysia",
                "description": "sovereign state in Southeast Asia"
            },
            "score": 4.0,
            "type": "GPE",
            "name": "Malaysia"
        },
        {
            "info": {
                "wikipedia": "China",
                "description": "sovereign state in East Asia"
            },
            "score": 3.6,
            "type": "GPE",
            "name": "China"
        },
        {
            "info": {
                "wikipedia": "Putrajaya",
                "description": "federal administrative centre of Malaysia"
            },
            "score": 1.8,
            "type": "GPE",
            "name": "Putrajaya"
        },
        {
            "info": {
                "wikipedia": null,
                "description": null
            },
            "score": 0.5,
            "type": "ORG",
            "name": "Malaysia Airlines"
        },
        {
            "info": {
                "wikipedia": null,
                "description": null
            },
            "score": 0.5,
            "type": "ORG",
            "name": "MH370"
        }
  ]
}

Identify people, places, and organizations in your text

This API detects named entities and classify them as Person, Place, Organization or Misc. The service also links them to knowledge base repositories (Wikipedia, DBpedia, etc.). It is also possible to include custom whitelists and blacklists of entities upon request. Allowed input sources are: text content contained in an URL ("from URL") or just simple text ("from text").

Entity Extraction - POST fromURL

Attribute Type Description Values
url string, required the URL of the text document use url-encoding
Parameter Type Description
limit number, optional max # of relevant entities to be returned, in decreasing order of confidence (if not specified, all results are returned)
profile string, optional either precision (default) or recall
access_token string, required your access token (40 digits)

Examples of how-to-call the API and the related output are provided in the right panel.

Entity Extraction - POST fromText

Attribute Type Description Values
text string, required the text to be classified pass the text between "" (e.g. "This is an example") or use url-encoded text
Parameter Type Description
limit number, optional max # of relevant entities to be returned, in decreasing order of confidence (if not specified, all results are returned)
profile string, optional either precision (default) or recall
access_token string, required your access token (40 digits)

Examples of how-to-call the API and the related output are provided in the right panel.

Keyword Extraction

Request example - POST fromURL...

curl --ssl-reqd --request POST --data url=https%3A%2F%2Fwww.theguardian.com%2Fworld%2F2016%2Fjul%2F22%2Fmissing-flight-mh370-hunt-for-debris-will-not-be-extended "https://api.yonderlabs.com/2.0/text/keywordextraction/fromURL?limit=12&access_token=YOUR_ACCESS_TOKEN"

... and response body (200/JSON):

{
  "url": "https://www.theguardian.com/world/2016/jul/22/missing-flight-mh370-hunt-for-debris-will-not-be-extended", 
  "text": "The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...]", 
  "limit": 12, 
  "keywords": [
        {
            "score": 1.0,
            "name": "search area"
        },
        {
            "score": 0.9,
            "name": "current search area"
        },
        {
            "score": 0.9,
            "name": "priority search area"
        },
        {
            "score": 0.9,
            "name": "total search area"
        },
        {
            "score": 0.8,
            "name": "underwater search"
        },
        {
            "score": 0.7,
            "name": "area"
        },
        {
            "score": 0.7,
            "name": "hunt"
        },
        {
            "score": 0.7,
            "name": "search"
        },
        {
            "score": 0.6,
            "name": "evidence"
        },
        {
            "score": 0.6,
            "name": "new evidence"
        },
        {
            "score": 0.5,
            "name": "aircraft"
        },
        {
            "score": 0.5,
            "name": "credible evidence"
        }
    ]
}

Request example - POST fromText...

curl --ssl-reqd --request POST --data text="The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...]" "https://api.yonderlabs.com/2.0/text/keywordextraction/fromText?limit=12&access_token=YOUR_ACCESS_TOKEN"

... and response body (200/JSON):

{
    "url": null,
    "text": "The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...]",
    "limit": 12,
    "keywords": [
        {
            "score": 1.0,
            "name": "current search area"
        },
        {
            "score": 0.9,
            "name": "search"
        },
        {
            "score": 0.8,
            "name": "missing jet"
        },
        {
            "score": 0.7,
            "name": "evidence"
        },
        {
            "score": 0.7,
            "name": "hunt"
        },
        {
            "score": 0.5,
            "name": "current area"
        },
        {
            "score": 0.5,
            "name": "majority"
        },
        {
            "score": 0.4,
            "name": "airline"
        },
        {
            "score": 0.4,
            "name": "country"
        },
        {
            "score": 0.4,
            "name": "future"
        },
        {
            "score": 0.4,
            "name": "home"
        },
        {
            "score": 0.2,
            "name": "transport ministers"
        }
    ]
}

Find meaningful keywords in your text document

This API analyzes your text content (news articles, blog posts, e-mail, etc.) identifying all meaningful keywords related to important facts, events and relations. Allowed input sources are: text content contained in an URL ("from URL") or just simple text ("from text").

Keyword Extraction - POST fromURL

Attribute Type Description Values
url string, required the URL of the text document use url-encoding
Parameter Type Description
limit number, optional max # of relevant keywords to be returned, in decreasing order of relevance (if not specified, all results are returned)
profile string, optional either balanced (default) or verbose
access_token string, required your access token (40 digits)

Profiles:

Examples of how-to-call the API and the related output are provided in the right panel.

Keyword Extraction - POST fromText

Attribute Type Description Values
text string, required the text to be classified pass the text between "" (e.g. "This is an example") or use url-encoded text
Parameter Type Description
limit number, optional max # of relevant keywords to be returned, in decreasing order of relevance (if not specified, all results are returned)
profile string, optional either balanced (default) or verbose
access_token string, required your access token (40 digits)

Profiles:

Language Detection

Request example - POST fromURL...

curl --ssl-reqd --request POST --data url=https%3A%2F%2Fwww.theguardian.com%2Fworld%2F2016%2Fjul%2F22%2Fmissing-flight-mh370-hunt-for-debris-will-not-be-extended "https://api.yonderlabs.com/2.0/text/languagedetection/fromURL?access_token=YOUR_ACCESS_TOKEN"

... and response body (200/JSON):

{
  "url": "https://www.theguardian.com/world/2016/jul/22/missing-flight-mh370-hunt-for-debris-will-not-be-extended", 
  "text": "The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...]", 
  "lang-ext": "English", 
  "lang": "en"
}

Request example - POST fromText...

curl --ssl-reqd --request POST --data text="The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...]" "https://api.yonderlabs.com/2.0/text/languagedetection/fromText?access_token=YOUR_ACCESS_TOKEN"

... and response body (200/JSON):

{
  "url": null, 
  "text": "The hunt for Malaysia Airlines flight MH370 is to be suspended if evidence of the missing jet is not found in the current search area. The transport ministers of Australia, Malaysia and China, representing the country leading the search, the airline and the home of the majority of its passengers, met to discuss the future of the search in the Malaysian federal administrative centre of Putrajaya on Friday. They announced that [...]", 
  "lang-ext": "English", 
  "lang": "en"
}

Recognize the language of your text (over 100 languages)

This service recognizes the language a document were written in, including English, Italian, Spanish, French, German, and other main languages. Allowed input sources are: text content contained in an URL ("from URL") or just simple text ("from text").

Language Extraction - POST fromURL

Attribute Type Description Values
url string, required the URL of the text document use url-encoding
Parameter Type Description
access_token string, required your access token (40 digits)

Examples of how-to-call the API and the related output are provided in the right panel.

Language Extraction - POST fromText

Attribute Type Description Values
text string, required the text to be classified pass the text between "" (e.g. "This is an example") or use url-encoded text
Parameter Type Description
access_token string, required your access token (40 digits)

Examples of how-to-call the API and the related output are provided in the right panel.

Return Codes & Errors

YonderAPI returns codes that follow the HTTP standard.

Successfull requests

When everything goes fine, YonderAPI returns HTTP codes of the type 2xx:

Error Code Meaning
200 OK
201 CREATED
202 ACCEPTED
204 NO CONTENT

Client-side errors

When something goes wrong on the request side, YonderAPI returns HTTP error codes of type 4xx:

Error Code Meaning
400 BAD REQUEST (e.g. a required parameter is missing)
401 UNAUTHORIZED (e.g. wrong credentials)
404 NOT FOUND (e.g. misspelled resource)
405 METHOD NOT ALLOWED (e.g. GET is requested but only POST is available)
422 CLASSIFIER ERROR (e.g. the classifier was not trained on these input values)

Error messages are self-explanatory and clearly point where the problem is. Examples of some possible error responses are provided aside:

{
    "message": {
        "language": "AR language is not supported."
    }
}

{
    "message": {
        "language": "Text and taxonomy languages do not match."
    }
}

{
    "message": {
        "text": "Text too short."
    }
}

{
    "message": {
        "text": "Missing required parameter in the post body."
    }
}

{
    "message": {
        "url": "Missing required parameter in the post body."
    }
}

{
    "message": {
        "url ": "Extracted text is empty. Invalid URL?"
    }
}

{
    "message": {
        "limit": "Value is too low: the minimum accepted is 3."
    }
}

{
    "message": {
        "ratelimit": "Limit of 1000000 requests/day reached for endpoint languagedetection."
    }
}

{
    "message": {
        "url": "Unsuccessful text extraction. Invalid URL?"
    }
}

{
  "message": {
    "collection": "The collection you are trying to create already exists."
  }
}

{
  "message": {
    "collection": "The collection you are trying to access does not exist."
  }
}

{
  "message": {
    "collection": "Error while processing your request."
  }
}

{
  "message": {
    "collection": "The document you are trying to access does not exist."
  }
}

{
  "message": {
    "collection": "The id is not a valid ObjectId."
  }
}

{
  "message": {
    "collection": "The collection name you choose is reserved."
  }
}

{
  "message": {
    "collection": "The collection you are trying to access is full (100,000 documents)."
  }
}

{
  "message": {
    "collection": "You reached the maximum allowed number of collections (1000)."
  }
}

{
  "message": {
    "classifier": <classifier_error_description>
  }
}

Server-side errors

When something goes wrong on the API side, YonderAPI returns HTTP error code 500 INTERNAL SERVER ERROR with a message body such as the ones provided aside:

{
    "message": {
        "error": "API processing error - Code 001." 
    }
}
cURL