Natural Language Understanding API Overview

This tutorial guides you through our Natural Language Understanding API. The API comprises two services: the Entity Linking Service and the Knowledge Graph Service. The API is in version v2 which was released on March 13, 2017.

We encourage you to experiment with the example API requests listed on this page. To do so, you can directly go ahead paste the provided snippets into your shell (given that curl is installed). If you prefer making calls from a sophisticated UI, we suggest that you use the interactive API Documentation.

Our API is secured with an OAuth 2 authentication layer. No matter which tool you use for making your request, always make sure to replace the ACCESS_TOKEN parameter with a proper value as described below.

Sign up as a Developer

Before reading on, make sure that you sign up as a developer first. Once you confirm your registration, an OAuth 2 client application will be provisioned for you automatically, and its credentials will be shown to you in the developer portal. This information is required by the next steps.

Get an OAuth 2 Access Token

Our API is secured with an OAuth 2 authentication layer. Currently, we support the Client Credentials flow which allows your client application to directly request an access token from the endpoint at https://api.ambiverse.com/oauth/token.

Get the ACCESS_TOKEN via curl

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=CLIENT_ID" \
     -d "client_secret=CLIENT_SECRET" \
     "https://api.ambiverse.com/oauth/token"

Make sure to replace CLIENT_IDand CLIENT_SECRET with your OAuth 2 client credentials. As said above, you can find them in the developer portal.

Get the ACCESS_TOKEN via the interactive API Documentation

To execute this request using the interactive API Documentation, navigate to Section OAuth 2 Authorization and click on the /token POST method. Make sure that you are logged in to the developer portal, as then you will be able to get the CLIENT_ID and CLIENT_SECRET automatically from within the documentation page: Click on the corresponding text fields and pick your credentials from the popup menu. Click the "Try Out" button to get your access_token.

 

The raw response from our authentication layer will look like the following.

{
  "token_type": "bearer",
  "access_token": "ce4cdf4ddb5e44a08e3dbb86724a0837",
  "expires_in": 86400
}

Use the ACCESS_TOKEN

The access_token is valid for 24 hours and needs to be passed along with any API request. Note that a refresh token is not issued with the Client Credentials flow.

According to the specification, there are multiple ways how you can pass the token along. We recommend to use the request header field: For that, you define a key-value pair in your request header and set key to Authorization and it’s value to Bearer ACCESS_TOKEN (replace ACCESS_TOKEN with a proper token).

With curl, this is done by appending the -H flag to your call:

-H "Authorization: Bearer ACCESS_TOKEN"

In the interactive API Documentation, you just have to fill the parameter AUTHORIZATION with the ACCESS_TOKEN obtained previously.

 

As an alternative to passing the access token in the header, you can append it to the query string. However, this method is discouraged due to security weaknesses. If you want to use it regardless, then your URL will look like this:

https://api.ambiverse.com/<version>/<service>/<resource-or-method>?access_token=ACCESS_TOKEN

In the following sections, we explain what resources and methods are available for both the Entity Linking Service and the Knowledge Graph Service. The full API documentation can be found in the API Documentation section of the developer portal.

Entity Linking Service

Given a natural language text, our Entity Linking Service hosted at https://api.ambiverse.com/v2/entitylinking matches ambiguous names onto canonical entities (e.g. individuals, organizations, or places) registered in the YAGO-based Ambiverse Knowledge Graph.

Take the example sentence below:

Ma founded Alibaba in Hangzhou with investments from SoftBank and Goldman.

Our API will first spot all the names in this sentence: "Ma", "Alibaba", "Hangzhou", "SoftBank", and "Goldman".

These ambiguous names are now resolved by identifying the entity each name refers to. In the example, "Ma" is one of the most common family names in China and thus highly ambiguous. Here, it refers to Jack Ma, a Chinese businessman. "Alibaba" refers to Alibaba Group which he founded, not the character from Arabian literature or an Australian retail food franchise. "Hangzhou" is the capital of Zhejiang Province in east China, and "SoftBank" is SoftBank Group, a telecommunications and Internet corporation. "Goldman" is another highly ambiguous name that refers to people, communities, music bands, schools, and even mathematical equations. In this context, however, it refers to the investment banking firm Goldman Sachs.

The output of the analysis process will be Wikidata identifiers describing all these entities:

  • "Ma": http://www.wikidata.org/entity/Q1137062
  • "Alibaba": http://www.wikidata.org/entity/Q1359568
  • "Hangzhou": http://www.wikidata.org/entity/Q4970
  • "SoftBank": http://www.wikidata.org/entity/Q201653
  • "Goldman": http://www.wikidata.org/entity/Q193326

We’ll tell you later on in this document how you can use these identifiers to look up further details on the entities using our Knowledge Graph Service.

From a developer’s perspective, you can run the analysis by sending this JSON payload to our endpoint at https://api.ambiverse.com/v2/entitylinking/analyze:

{
  "docId": "ma-alibaba-investments",
  "text": "Ma founded Alibaba in Hangzhou with investments from SoftBank and Goldman."
}

The docId parameter is optional, but helps you keep track of your request in case you send multiple ones simultaneously. The text parameter takes a natural language text that is the subject of analysis. While we recognize names automatically, you can also enforce a name match during the analysis process by adding objects in the annotatedMentions array as a part of the JSON input. The objects consist of charLength and charOffset, and represent the position and the length of the name you want to be matched. For details, refer to the API Documentation.

If you want to run the example from your shell, execute this curl call (make sure to replace ACCESS_TOKEN with a proper value):

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -d '{
          "docId": "ma-alibaba-investments",
          "text": "Ma founded Alibaba in Hangzhou with investments from SoftBank and Goldman."
         }' \
     "https://api.ambiverse.com/v2/entitylinking/analyze"

The response you’ll get in JSON format looks like this:

{
  "docId": "ma-alibaba-investments",
  "language": "en",
  "matches": [
    {
      "charLength": 2,
      "charOffset": 0,
      "text": "Ma",
      "entity": {
        "id": "http://www.wikidata.org/entity/Q1137062",
        "confidence": 0.24400826614263774
      }
    },
    {
      "charLength": 7,
      "charOffset": 11,
      "text": "Alibaba",
      "entity": {
        "id": "http://www.wikidata.org/entity/Q1359568",
        "confidence": 0.895955178187174
      }
    },
    {
      "charLength": 8,
      "charOffset": 22,
      "text": "Hangzhou",
      "entity": {
        "id": "http://www.wikidata.org/entity/Q4970",
        "confidence": 0.9229612543325116
      }
    },
    {
      "charLength": 8,
      "charOffset": 53,
      "text": "SoftBank",
      "entity": {
        "id": "http://www.wikidata.org/entity/Q201653",
        "confidence": 0.954021817469926
      }
    },
    {
      "charLength": 7,
      "charOffset": 66,
      "text": "Goldman",
      "entity": {
        "id": "http://www.wikidata.org/entity/Q193326",
        "confidence": 0.41802014708618046
      }
    }
  ],
  "entities": [
    {
      "id": "http://www.wikidata.org/entity/Q1137062",
      "name": "Jack Ma",
      "url": "http://en.wikipedia.org/wiki/Jack%20Ma",
      "type": "PERSON",
      "salience": 0.7256598749663603
    },
    {
      "id": "http://www.wikidata.org/entity/Q1359568",
      "name": "Alibaba Group",
      "url": "http://en.wikipedia.org/wiki/Alibaba%20Group",
      "type": "ORGANIZATION",
      "salience": 0.5163823048005602
    },
    {
      "id": "http://www.wikidata.org/entity/Q4970",
      "name": "Hangzhou",
      "url": "http://en.wikipedia.org/wiki/Hangzhou",
      "type": "LOCATION",
      "salience": 0.34844721607983514
    },
    {
      "id": "http://www.wikidata.org/entity/Q201653",
      "name": "SoftBank Group",
      "url": "http://en.wikipedia.org/wiki/SoftBank%20Group",
      "type": "ORGANIZATION",
      "salience": 0.15870666288011434
    },
    {
      "id": "http://www.wikidata.org/entity/Q193326",
      "name": "Goldman Sachs",
      "url": "http://en.wikipedia.org/wiki/Goldman%20Sachs",
      "type": "ORGANIZATION",
      "salience": 0.1583793877976444
    }
  ]
}

The matches array contains a list of objects that link names to entities. For example, the first name "Ma" (text parameter) was spotted at character offset 0 (charOffset, starting at 0) with a length of 2 characters (charLength). Our API further linked the name "Ma" to the entity with the unique ID (id) http://www.wikidata.org/entity/Q1137062 and is quite sure given the short context. This is represented as confidence of 0.24400826614263774(always in a range of [0,1], the higher the more confident) that this entity is the correct choice in the given context.

The entities array contains all unique entities that appear in the document. An entity is represented as id of the entity, name, wikipedia url and the high level type of the entity. Possible entity types are: PERSON, LOCATION, ORGANIZATION, EVENT, ARTIFACT, OTHER and UNKNOWN for entities where the type is not present. The entity object contains the entity salience score which represents the importance of the entity for the given text, in a range of [0,1].

If you want to learn more about all the great things you can do with the knowledge graph IDs that names were linked to in this process, keep reading on :)

Knowledge Graph Service

Our Knowledge Graph Service hosted at https://api.ambiverse.com/v2/knowledgegraph allows you to search and browse the YAGO-based Ambiverse Knowledge Graph, providing you with detailed information for all canonical entities (such as Jack Ma from the above example) and the categories that are assigned to them (e.g. person, organization, location, etc.). The Knowledge Graph Service is particularly suited to be run as a second step after ambiguous names that occur in natural language texts have been matched onto canonical entities as described above.

The current version of our API uses a static Wikipedia dump that was generated on March 20, 2017. We currently support English, Spanish, Chinese, and German, and more languages will be added in the future.

Take for example the entities that we identified in the previous step, like http://www.wikidata.org/entity/Q1137062 for "Ma" or http://www.wikidata.org/entity/Q1359568 for "Alibaba". We guess you are curious to learn more about these entities? So let’s query the knowledge graph by sending a JSON payload to the endpoint at https://api.ambiverse.com/v2/knowledgegraph/entities:

[
  "http://www.wikidata.org/entity/Q1137062",
  "http://www.wikidata.org/entity/Q1359568"
]

If you want to run the example from your shell, execute this curl call (make sure to replace ACCESS_TOKEN with a proper value):

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -d '[
           "http://www.wikidata.org/entity/Q1137062",
           "http://www.wikidata.org/entity/Q1359568"
         ]' \
     "https://api.ambiverse.com/v2/knowledgegraph/entities"

The response you’ll get in JSON format looks like this:

{
  "entities": {
    "http://www.wikidata.org/entity/Q1137062": {
      "id": "http://www.wikidata.org/entity/Q1137062",
      "type": "PERSON",
      "names": {
        "en": {
          "language": "en",
          "value": "Jack Ma"
        },
        "de": {
          "language": "de",
          "value": "Jack Ma"
        },
        "es": {
          "language": "es",
          "value": "Jack Ma"
        },
        "zh": {
          "language": "zh",
          "value": "马云"
        }
      },
      "descriptions": {
        "en": {
          "language": "en",
          "value": "Chinese businessman"
        },
        "de": {
          "language": "de",
          "value": "chinesischer Unternehmer"
        },
        "es": {
          "language": "es",
          "value": "empresario chino"
        },
        "zh": {
          "language": "zh",
          "value": "中国商人"
        }
      },
      "detailedDescriptions": {
        "en": {
          "language": "en",
          "value": "Ma Yun, known professionally as Jack Ma, is a Chinese business magnate who is the founder and executive chairman of Alibaba Group, a family of successful Internet-based businesses. Throughout his life, Jack Ma has became a global icon in business and entrepreneurship, as well as one of the world's most influential businessmen. He is also a philanthropist and is known for expounding his philosophy of business."
        },
        "de": {
          "language": "de",
          "value": "Jack Ma ist ein chinesischer Unternehmer und Philanthrop. Er ist der Gründer und CEO der Alibaba Group, einer Gruppe von erfolgreichen Internet-basierten Unternehmen. Er ist die erste Person vom chinesischen Festland, die auf dem Titelblatt des Magazins Forbes abgebildet war."
        },
        "es": {
          "language": "es",
          "value": "Jack Ma o Ma Yun o The Boss"
        },
        "zh": {
          "language": "zh",
          "value": "马云(英文名:,),祖籍浙江省绍兴嵊州市(原嵊县)谷来镇,后父母移居杭州,出生于浙江省杭州市,中国企业家,曾为亚洲首富,现任阿里巴巴集团董事局主席、淘宝网、支付宝的创始人和日本軟銀董事,大自然保護協會,中國理事會主席兼全球董事會成員,華誼兄弟董事,生命科學突破獎基金會董事。"
        }
      },
      "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/3/38/Jack_Ma_2008.jpg",
        "licenses": [
          {
            "name": "GNUFreeDocumentationLicense",
            "url": "https://www.gnu.org/licenses/gfdl"
          },
          {
            "name": "CreativeCommonsLicense-BY-SA-2.0",
            "url": "https://creativecommons.org/licenses/by-sa/2.0"
          }
        ],
        "author": {
          "name": "World Economic Forum",
          "url": "http://en.wikipedia.org/wiki/User:World_Economic_Forum"
        }
      },
      "links": {
        "en": {
          "language": "en",
          "value": "http://en.wikipedia.org/wiki/Jack_Ma"
        },
        "de": {
          "language": "de",
          "value": "http://de.wikipedia.org/wiki/Jack_Ma"
        },
        "es": {
          "language": "es",
          "value": "http://es.wikipedia.org/wiki/Jack_Ma"
        },
        "zh": {
          "language": "zh",
          "value": "http://zh.wikipedia.org/wiki/%E9%A9%AC%E4%BA%91"
        }
      },
      "categories": [
        "YAGO3:<wordnet_physical_entity_100001930>",
        "YAGO3:<wikicat_People_associated_with_places>",
        "YAGO3:<wikicat_Educators_from_Zhejiang>",
        "YAGO3:<wikicat_Asian_people>",
        "YAGO3:<wordnet_living_thing_100004258>",
        "YAGO3:<wikicat_People_who_work_with_children>",
        "YAGO3:<wikicat_Physical_objects>",
        "YAGO3:<wikicat_Educators>",
        "YAGO3:<wikicat_People_from_Hangzhou>",
        "YAGO3:<wikicat_People_in_technology>",
        "YAGO3:<wordnet_important_person_110200781>",
        "YAGO3:<wordnet_practitioner_110462860>",
        "YAGO3:<wordnet_man_110287213>",
        "YAGO3:<wikicat_Wushu_practitioners>",
        "YAGO3:<wikicat_Chinese_Internet_celebrities>",
        "YAGO3:<wordnet_billionaire_110529684>",
        "YAGO3:<wordnet_professional_110480253>",
        "YAGO3:<wikicat_Artificial_objects>",
        "YAGO3:<wikicat_Chinese_people>",
        "YAGO3:<wikicat_People_associated_with_animals>",
        "YAGO3:<wikicat_People_from_Zhejiang>",
        "YAGO3:<wikicat_Billionaires_from_Zhejiang>",
        "YAGO3:<wikicat_Billionaires>",
        "YAGO3:<wordnet_person_100007846>",
        "YAGO3:<wordnet_celebrity_109903153>",
        "YAGO3:<wikicat_People_associated_with_animal_welfare_and_rights>",
        "YAGO3:<wikicat_Chinese_educators>",
        "YAGO3:<yagoLegalActorGeo>",
        "YAGO3:<wordnet_adult_109605289>",
        "YAGO3:<wordnet_causal_agent_100007347>",
        "YAGO3:<wordnet_rich_person_110529231>",
        "YAGO3:<wikicat_People_from_East_China>",
        "YAGO3:owl:Thing",
        "YAGO3:<wikicat_T'ai_chi_ch'uan_practitioners>",
        "YAGO3:<wikicat_East_Asian_people>",
        "YAGO3:<wikicat_Living_people>",
        "YAGO3:<wikicat_Men>",
        "YAGO3:<wikicat_People>",
        "YAGO3:<wikicat_Educators_from_Hangzhou>",
        "YAGO3:<wordnet_whole_100003553>",
        "YAGO3:<wordnet_educator_110045713>",
        "YAGO3:<wikicat_Alibaba_Group_people>",
        "YAGO3:<wikicat_Chinese_billionaires>",
        "YAGO3:<wikicat_Objects>",
        "YAGO3:<wikicat_Internet_people>",
        "YAGO3:<wikicat_People_associated_with_buildings_and_structures>",
        "YAGO3:<wikicat_Media_people>",
        "YAGO3:<wikicat_Internet_celebrities>",
        "YAGO3:<wordnet_male_109624168>",
        "YAGO3:<wordnet_object_100002684>",
        "YAGO3:<wordnet_organism_100004475>",
        "YAGO3:<yagoLegalActor>"
      ]
    },
    "http://www.wikidata.org/entity/Q1359568": {
      "id": "http://www.wikidata.org/entity/Q1359568",
      "type": "ORGANIZATION",
      "names": {
        "en": {
          "language": "en",
          "value": "Alibaba Group"
        },
        "de": {
          "language": "de",
          "value": "Alibaba Group"
        },
        "es": {
          "language": "es",
          "value": "Alibaba Group"
        },
        "zh": {
          "language": "zh",
          "value": "阿里巴巴集团"
        }
      },
      "descriptions": {
        "en": {
          "language": "en",
          "value": "Hangzhou-based group of Internet-based e-commerce businesses"
        },
        "zh": {
          "language": "zh",
          "value": "中国网络公司"
        }
      },
      "detailedDescriptions": {
        "en": {
          "language": "en",
          "value": "Alibaba Group Holding Limited is a Chinese e-commerce company that provides consumer-to-consumer, business-to-consumer and business-to-business sales services via web portals. It also provides electronic payment services, a shopping search engine and data-centric cloud computing services. The group began in 1999 when Jack Ma founded the website Alibaba.com, a business-to-business portal to connect Chinese manufacturers with overseas buyers. In 2012, two of Alibaba's portals handled 1.1 trillion yuan in sales. but the company primarily operates in the People's Republic of China. At closing time on the date of its initial public offering, 19 September 2014, Alibaba's market value was US$231 billion. However, the stock has traded down and market cap was about $212 billion at the end of December 2015."
        },
        "de": {
          "language": "de",
          "value": "Die Alibaba Group Holding Limited ist ein Unternehmen mit Sitz in Hangzhou, China. Es wurde von dem ehemaligen Englischlehrer Jack Ma im Jahr 1999 gegründet An dem Unternehmen sind u. a. Yahoo und Softbank beteiligt."
        },
        "es": {
          "language": "es",
          "value": "Alibaba Group es un consorcio privado chino con sede en Hangzhou dedicado al comercio electrónico en Internet, incluyendo portales de ventas business-to-business, de venta al por menor, y de venta entre consumidores también ofrece servicios de pago en línea, un motor de búsqueda de comparación de precios y servicios de almacenamiento de datos en la nube. En 2012, dos de los portales de Alibaba juntos manejaron 1,1 billones de yuanes en ventas, más que sus competidores eBay y Amazon.com combinados. Durante 2013 consiguió unos ingresos aproximados de 7500 millones de dólares y poseía unos 22 000 empleados en marzo de 2014."
        },
        "zh": {
          "language": "zh",
          "value": "阿里巴巴集團(英語:Alibaba Group),()创立于1999年,是一間提供電子商務線上交易平台的公司,業務包括B2B貿易、網上零售、購物搜索引擎、第三方支付和雲計算服務。集團的子公司及關聯公司有阿里巴巴B2B集團概況-阿里巴巴集團"
        }
      },
      "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/9/99/Alibaba_group_Headquarters.jpg",
        "licenses": [
          {
            "name": "CreativeCommonsLicense-BY-SA-3.0",
            "url": "https://creativecommons.org/licenses/by-sa/3.0"
          }
        ],
        "author": {
          "name": "Thomas LOMBARD",
          "url": "https://commons.wikimedia.org/wiki/User:Thecraft"
        }
      },
      "links": {
        "en": {
          "language": "en",
          "value": "http://en.wikipedia.org/wiki/Alibaba_Group"
        },
        "de": {
          "language": "de",
          "value": "http://de.wikipedia.org/wiki/Alibaba_Group"
        },
        "es": {
          "language": "es",
          "value": "http://es.wikipedia.org/wiki/Alibaba_Group"
        },
        "zh": {
          "language": "zh",
          "value": "http://zh.wikipedia.org/wiki/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B4%E9%9B%86%E5%9B%A2"
        }
      },
      "categories": [
        "YAGO3:<wikicat_Wikipedia_categories_named_after_organizations>",
        "YAGO3:<wikicat_Financial_services_companies>",
        "YAGO3:<wikicat_Networking_companies>",
        "YAGO3:<wikicat_Business_services_companies>",
        "YAGO3:<wikicat_Trading_companies>",
        "YAGO3:<wikicat_Service_companies>",
        "YAGO3:<wikicat_Privately_held_companies>",
        "YAGO3:<wikicat_Silver_Lake_Partners>",
        "YAGO3:<wikicat_Multinational_companies>",
        "YAGO3:<wikicat_Computer_network_organizations>",
        "YAGO3:<wordnet_group_100031264>",
        "YAGO3:<wikicat_Computer_companies>",
        "YAGO3:<wikicat_Publicly_traded_companies>",
        "YAGO3:<wikicat_Organizations_based_in_Asia>",
        "YAGO3:<wikicat_Companies_based_in_New_York_City>",
        "YAGO3:<wikicat_Internet_companies_of_China>",
        "YAGO3:<yagoPermanentlyLocatedEntity>",
        "YAGO3:<wikicat_Financial_services_companies_based_in_New_York_City>",
        "YAGO3:<wikicat_Information_technology_companies_of_China>",
        "YAGO3:<wikicat_Financial_services_companies_of_the_United_States>",
        "YAGO3:<wikicat_Technology_companies>",
        "YAGO3:<wikicat_Companies_of_Asia>",
        "YAGO3:<wikicat_Retail_companies_of_China>",
        "YAGO3:<wordnet_abstraction_100002137>",
        "YAGO3:<wikicat_Internet-related_organizations>",
        "YAGO3:<wikicat_Privately_held_companies_of_China>",
        "YAGO3:<wikicat_Organizations_based_in_California>",
        "YAGO3:<wikicat_Organizations_based_in_New_York>",
        "YAGO3:<wikicat_Companies_established_in_1999>",
        "YAGO3:<wikicat_Publicly_traded_companies_of_the_United_States>",
        "YAGO3:<wikicat_Financial_services_companies_established_in_1999>",
        "YAGO3:<wikicat_Multinational_companies_headquartered_in_China>",
        "YAGO3:<wikicat_Organizations_based_in_China>",
        "YAGO3:<wikicat_Technology_organizations>",
        "YAGO3:<wikicat_Service_companies_of_the_United_States>",
        "YAGO3:<wikicat_Financial_services_companies_established_in_the_20th_century>",
        "YAGO3:<wikicat_Organizations_established_in_the_20th_century>",
        "YAGO3:<wikicat_Companies_based_in_California>",
        "YAGO3:<wikicat_Information_technology_organisations>",
        "YAGO3:<wikicat_Wikipedia_categories_named_after_organizations_based_in_North_America>",
        "YAGO3:<wikicat_Digital_media>",
        "YAGO3:<wikicat_Wikipedia_categories_named_after_organizations_based_in_the_United_States>",
        "YAGO3:<wikicat_Online_companies>",
        "YAGO3:<wikicat_Financial_services_organizations>",
        "YAGO3:<wikicat_Self-regulatory_organizations>",
        "YAGO3:<wikicat_Organizations_based_in_North_America>",
        "YAGO3:<wikicat_Organizations>",
        "YAGO3:<wikicat_Companies_based_in_Hangzhou>",
        "YAGO3:<wikicat_Wikipedia_categories_named_after_financial_services_companies_of_the_United_States>",
        "YAGO3:<wikicat_Wikipedia_categories_named_after_companies>",
        "YAGO3:<wikicat_Retail_companies_of_Asia>",
        "YAGO3:<wikicat_Economy-related_organizations>",
        "YAGO3:<wikicat_Art_media>",
        "YAGO3:<wikicat_Wikipedia_categories_named_after_financial_services_companies>",
        "YAGO3:<wikicat_Companies_listed_on_the_New_York_Stock_Exchange>",
        "YAGO3:<wordnet_social_group_107950920>",
        "YAGO3:<wikicat_Chinese_companies_established_in_1999>",
        "YAGO3:<wikicat_Computer-related_organizations>",
        "YAGO3:<wikicat_Companies_based_in_the_San_Francisco_Bay_Area>",
        "YAGO3:<wikicat_Organizations_of_the_Americas>",
        "YAGO3:<yagoLegalActorGeo>",
        "YAGO3:<wikicat_Internet_companies>",
        "YAGO3:<wikicat_Defunct_organizations>",
        "YAGO3:<wikicat_Companies_based_in_San_Mateo_County,_California>",
        "YAGO3:<wikicat_Technology_companies_of_China>",
        "YAGO3:<wikicat_Organizations_based_in_the_United_States>",
        "YAGO3:owl:Thing",
        "YAGO3:<wikicat_Silver_Lake_Partners_companies>",
        "YAGO3:<wikicat_Wikipedia_categories_named_after_companies_of_the_United_States>",
        "YAGO3:<wikicat_Companies_based_in_Menlo_Park,_California>",
        "YAGO3:<wikicat_Companies>",
        "YAGO3:<wikicat_Companies_established_in_the_20th_century>",
        "YAGO3:<wikicat_Organizations_based_in_the_San_Francisco_Bay_Area>",
        "YAGO3:<wikicat_Companies_of_North_America>",
        "YAGO3:<wikicat_Organizations_based_in_New_York_City>",
        "YAGO3:<wikicat_Defunct_companies>",
        "YAGO3:<wikicat_Information_technology_companies>",
        "YAGO3:<wikicat_Companies_based_in_Zhejiang>",
        "YAGO3:<wikicat_Companies_based_in_New_York>",
        "YAGO3:<wordnet_company_108058098>",
        "YAGO3:<wordnet_institution_108053576>",
        "YAGO3:<wikicat_Companies_based_in_Silicon_Valley>",
        "YAGO3:<wikicat_Companies_of_the_United_States>",
        "YAGO3:<wordnet_organization_108008335>",
        "YAGO3:<wikicat_Companies_of_China>",
        "YAGO3:<wikicat_Online_companies_of_China>",
        "YAGO3:<wikicat_Private_equity_portfolio_companies>",
        "YAGO3:<yagoLegalActor>"
      ]
    }
  }
}

The entities object is a map (id, Entity) for faster lookup. For the first entity http://www.wikidata.org/entity/Q1137062, in addition to the entity ID (id parameter) you’ll see the human-readable names in different languages (en, de, es, and zh). For some entities, where no Wikipedia page is present in certain language, the map does not contain this language code. A multilingual list of short descriptions, and a multilingual list of detailDescriptions give a human-readable entity description. The image object contains a public url of the enitity image, together with list of licenses under which this image is published and the author of the image. The links collection holds a url (which is URL-encoded) that points to the corresponding article in Wikipedia in the given languages. The categories collection finally lists all the assigned categories, where each category is referenced by its YAGO ID – for example YAGO3:<wikicat_Billionaires_from_Zhejiang> or YAGO3:<wikicat_Investment_banks>.

To resolve category IDs to human-readable names and descriptions, you can use the /categories API endpoint and send a JSON payload like this:

[
  "YAGO3:<wikicat_Billionaires>",
  "YAGO3:<wikicat_Investment_banks>"
]

In curl syntax, the query looks like this (again, make sure to replace ACCESS_TOKEN with a proper value):

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -d '[
           "YAGO3:<wikicat_Billionaires_from_Zhejiang>",
           "YAGO3:<wikicat_Investment_banks>"
         ]' \
     "https://api.ambiverse.com/v2/knowledgegraph/categories"

The response is as follows:

{
  "categories": {
    "YAGO3:<wikicat_Billionaires_from_Zhejiang>": {
      "id": "YAGO3:<wikicat_Billionaires_from_Zhejiang>",
      "name": "Billionaires from Zhejiang",
      "descriptions": {
        "en": {
          "language": "en",
          "value": "Billionaires whose birthplace or hometown is Zhejiang Province, PRC"
        }
      }
    },
    "YAGO3:<wikicat_Investment_banks>": {
      "id": "YAGO3:<wikicat_Investment_banks>",
      "name": "Investment banks"
    }
  }
}

The categories is a map (id, Category) containing additional data: human-readable names (YAGO3:<wikicat_Billionaires_from_Zhejian> reads as "Billionaires from Zhejiang") and descriptions in multiple languages.

Further Information

Ambiverse is a spin-off from the Max Planck Institute for Informatics and develops technologies to automatically understand, analyze, and manage Big Text Data collections. Ambiverse is built on years of state-of-the-art research in text analytics and in 2015 received an EXIST Transfer of Research grant by the German Federal Ministry for Economic Affairs and Energy.

If you’d like to learn more about us and our products, have a look at our website or contact us directly!