Migrating from AlchemyLanguage

Starting on April 7, 2017, it will no longer be possible to create a new instance of AlchemyAPI on Bluemix. Existing service instances will be supported until March 7, 2018. To continue using AlchemyLanguage features, you will need to migrate your code to Natural Language Understanding.

Natural Language Understanding offers a more economical pricing model and a consolidated API that is much easier to use. Existing features are streamlined to make them more useful and valuable for our customers needs. Natural Language Understanding makes it easier to manage your brand, gather business intelligence, and cluster for matching, ad-tech, and recommendations.

Overview of major changes

  • New API request syntax: send requests to the /analyze endpoint
  • New response structure (code that parses AlchemyLanguage output does not work for Natural Language Understanding output)
  • JSON is the only output format
  • Text extraction is enabled by setting the return_analyzed_text parameter to true
  • Microformats is not supported
  • Date extraction is not supported (Publication Date is still supported in the Metadata feature)
  • "quotations" options for entities are not supported
  • "knowledgeGraph" is not supported for concepts, keywords, or entities
  • Visual constraints queries (used with the cquery parameter) are not supported
  • JSONP callbacks are not supported
  • TypedRelations from AlchemyLanguage is Relations in Natural Language Understanding
  • Relations from AlchemyLanguage is Semantic Roles in Natural Language Understanding
  • Entity types have changed (see the new entity types here)

Migration steps

  1. Get started with the Natural Language Understanding service.
  2. If you use custom models from Watson Knowledge Studio, redeploy them to your new Natural Language Understanding service instance. Follow the steps for deploying rule-based annotators or machine-learning annotators, and select the Natural Language Understanding service as the target for deployment.
  3. Migrate your code. If you use the Watson Developer Cloud SDKs to interact with AlchemyLanguage, you need to change your SDK code. Click the following links to view Natural Language Understanding SDK examples in GitHub:

Additionally, you need to reconfigure any logic in your application that expects the output of AlchemyLanguage requests. Make sure that your code is adjusted to process the new output structure of Natural Language Understanding.

AlchemyLanguage methods and corresponding Natural Language Understanding features

AlchemyLanguage requests map to the Natural Language Understanding /analyze endpoint. Requests to /analyze are similar to Combined Call requests from AlchemyLanguage, but the syntax is different and you are able to specify options like limit individually for each feature. POSTs to /analyze accept a JSON body that contains the input and the parameters for the request, and GETs to /analyze accept query parameters that are analogous to the JSON parameter syntax.

AlchemyLanguage method AlchemyLanguage endpoint Natural Language Understanding feature
Authors /text/TextGetAuthors
/url/URLGetAuthors
Metadata
Concepts /html/HTMLGetRankedConcepts
/text/TextGetRankedConcepts
/url/URLGetRankedConcepts
Concepts
Date Extraction /html/HTMLExtractDates
/text/TextExtractDates
/url/URLExtractDates
Not supported
Emotion Analysis /html/HTMLGetEmotion
/text/TextGetEmotion
/url/URLGetEmotion
Emotion
Targeted Emotion /html/HTMLGetTargetedEmotion
/text/TextGetTargetedEmotion
/url/URLGetTargetedEmotion
Emotion (use the targets option)
Entities /html/HTMLGetRankedNamedEntities
/text/TextGetRankedNamedEntities
/url/URLGetRankedNamedEntities
Entities
Feed Detection /html/HTMLGetFeedLinks
/url/URLGetFeedLinks
Metadata
Keywords /html/HTMLGetRankedKeywords
/text/TextGetRankedKeywords
/url/URLGetRankedKeywords
Keywords
Language Detection /html/HTMLGetLanguage
/text/TextGetLanguage
/url/URLGetLanguage
Basic language detection is free in every request. Language metadata other than the ISO code is not returned.
Microformats /html/HTMLGetMicroformatData
/url/URLGetMicroformatData
Not supported
Publication Date /html/HTMLGetPubDate
/url/URLGetPubDate
Metadata
Relations /html/HTMLGetRelations
/text/TextGetRelations
/url/URLGetRelations
Semantic Roles
Typed Relations /html/HTMLGetTypedRelations
/text/TextGetTypedRelations
/url/URLGetTypedRelations
Relations
Sentiment Analysis /html/HTMLGetTextSentiment
/text/TextGetTextSentiment
/url/URLGetTextSentiment
Sentiment
Targeted Sentiment /html/HTMLGetTargetedSentiment
/text/TextGetTargetedSentiment
/url/URLGetTargetedSentiment
Sentiment (use the targets option)
Taxonomy /html/HTMLGetRankedTaxonomy
/text/TextGetRankedTaxonomy
/url/URLGetRankedTaxonomy
Categories
Text (cleaned) /html/HTMLGetText
/url/URLGetText
Set return_analyzed_text to true in any valid request to /analyze
Text (raw) /html/HTMLGetRawText
/url/URLGetRawText
Set return_analyzed_text to true and clean to false in any valid request to /analyze
Title Extraction /html/HTMLGetTitle
/url/URLGetTitle
Metadata

So, if you are making this combined call:

curl -X POST \
-d "outputMode=json" \
-d "extract=entities,keywords" \
-d "sentiment=1" \
-d "limit=1" \
-d "url=https://www.ibm.com/us-en/" \
"https://gateway.watsonplatform.net/calls/url/URLGetCombinedData?apikey=$API_KEY"

it would now look like this in Natural Language Understanding:

curl -X POST \
-H "Content-Type: application/json" \
-u "{username}":"{password}" \
-d @parameters.json "https://gateway.watsonplatform.net/natural-language-understanding/api/v1/analyze?version=2017-02-27"

With this parameters.json:

{
  "url": "https://www.ibm.com/us-en/",
  "features": {
    "entities": {
      "sentiment": true,
      "limit": 1
    },
    "keywords": {
      "sentiment": true,
      "limit": 1
    }
  }
}

Entity harmonization

If you were using the public models from AlchemyLanguage's TypedRelations method, you will need to change any code that expects the entity types from those models. The following table shows the mapping of TypedRelations entity types to Natural Language Understanding entity types.

TypedRelations entity type Natural Language Understanding Relations entity type
AGE Age
ANIMAL Animal
AWARD Award
CARDINAL Cardinal
DATE Date
DEGREE Degree
DISEASE HealthCondition
DURATION Duration
EMAIL EmailAddress
EVENT Event
FACILITY Facility
FOOD Food
GEOLOGICALOBJ GeographicFeature
GPE GeopoliticalEntity
LAW Law
LOCATION Location
MEASURE Measure
MONEY Money
ORDINAL Ordinal
ORGAN Anatomy
ORGANIZATION Organization
PEOPLE Person
PERCENT Percent
PERSONPEOPLE Person
PERSON Person
PHONE Phone
PLANT Plant
PRODUCT Product
SUBSTANCE Substance
TICKER Ticker
TIME Time
TITLEWORK TitleWork
VEHICLE Vehicle
WEAPON Weapon
WEATHER Weather
WEB Web
EVENT_AWARD Award
EVENT_BUSINESS EventBusiness
EVENT_COMMUNICATION EventCommunication
EVENT_CRIME Crime
EVENT_CUSTODY EventCustody
EVENT_DEMONSTRATION EventDemonstration
EVENT_DISASTER NaturalEvent
EVENT_EDUCATION EventEducation
EVENT_ELECTION EventElection
EVENT_LEGAL EventLegal
EVENT_LEGISLATION EventLegislation
EVENT_MEETING EventMeeting
EVENT_GATHERING EventGathering
EVENT_PERFORMANCE EventPerformance
EVENT_PERSONNEL EventPersonnel
EVENT_SPORTS SportingEvent
EVENT_VIOLENCE EventViolence
EVENT Event