Development Overview

This section provides information about the AlchemyLanguage service that is important to developers of applications that use the service.

AlchemyLanguage REST API Overview

The AlchemyLanguage service provides REST API calls that perform image extraction, recognition, tagging, and link extraction. The endpoint for these REST calls is

For a complete list of the REST calls in the AlchemyLanguage API, the parameters that they can take, and for an interactive API explorer that enables you to experiment with them, see the AlchemyLanguage API explorer.

REST APIs can be complex and verbose to call directly in the programming language that you are using for development, so we provide SDKs that simply the task of invoking our REST APIs from popular languages such as Java, Node.js, and Python. We also provide SDKs for languages that are associated with development for specific platforms, such as Swift for development on the iOS mobile platform. See the next section for more information about these SDKs.

AlchemyLanguage SDK Overview

As summarized in the previous section, the Watson Developer Cloud services provide REST API calls that can be used to invoke those services from any programming language with REST support. The Watson Developer Cloud team also provides SDKs that simplify application development in popular languages and for popular platforms. Developers that use other languages or who focus on other platforms can still use the REST APIs that the Watson Developer Cloud services provide.

The following SDKs are available for the Watson Developer Cloud services, including the AlchemyLanguage API:

  • SDK for iOS (Swift): Using this beta SDK requires that you install third-party dependencies such as ObjectMapper and Alamofire, which can be satisfied using the Carthage dependency management tool. You can install Carthage from its installer or using the Homebrew tool. See the Quickstart Guide for the iOS SDK for detailed installation and configuration information.

  • SDK for Java: Using this beta SDK only requires that you add the appropriate commands to integrate the Java SDK into your build process, as explained in the README file for the Java SDK, and that you understand the simplified functions that it provides.

  • SDK for Node.js: Using this SDK only requires that you execute the npm install watson-developer-cloud command to install the SDK locally, that your code includes a var watson = require('watson-developer-cloud'); statement, and that you understand the simplified functions that the SDK provides. See the README file for the Node SDK for more information.

  • SDK for Python: Using this beta SDK only requires that you execute the appropriate pip or easy_install commands to install the Python SDK on your system and that you understand the simplified functions that it provides. See the README for the Python SDK for more information.

To see documentation that provides sample code for using the Node.js and Java SDKs, and equivalent REST API calls, see the API reference.

The AlchemyAPI team provided older SDKs that supported the AlchemyLanguage APIs from the Android OS, C/C++, C#, Java, Node.js, Perl, PHP, and Python. These SDKs are all open source, and are available on GitHub. However, these SDKs are no longer supported by the Alchemy team at IBM, and will not be updated by IBM to support API enhancements and other changes. Please switch to using one of the supported SDKs that were listed earlier in this section.

Prerequisites for using the AlchemyLanguage APIs in an application

This section explains how to perform the tasks that are required in order to satisfy the prerequisites for using the AlchemyLanguage service in Bluemix and for executing the sample command that are provided in the Tutorials section of this documentation.

Getting a Bluemix Account

IBM Bluemix™ is the cloud platform in which you deploy applications that use IBM Watson™ Developer Cloud services Application Programming Interfaces (APIs). The Bluemix environment supports a variety of approaches to creating, deploying, and running applications. Your first step is in using any Watson Developer Cloud API is to create a Bluemix account by registering for Bluemix.

You can register for Bluemix by clicking the SIGN UP button in the upper right corner of the page at After registering, you will receive an email message that requires you to confirm your registration. Once you have done that, it can take upwards of 15 minutes for your account to become active.

After your registration is successful, you receive a free 30-day trial for all Watson services. After 30 days, free use of Watson beta and experimental services continues. All other Watson services, such as generally available services, offer a specified number of free API calls on a monthly or daily basis. Pricing varies for each service after you exceed the specified number of free calls. For more information, see the documentation for the service that you plan to use.

Once you have registered for Bluemix, you are ready to begin creating your first Watson services application by creating an instance of the WDC service that you want to use and obtaining the credentials which are necessary to use that service.

Getting an AlchemyLanguage Instance and API Key

To get started using the AlchemyLanguage API, you must complete the following steps to obtain your credentials. (You can also watch a quick video that shows the steps in this process.)

To obtain the credentials that are required to use the AlchemyLanguage API, do the following:

  1. Log in to Bluemix: Click the LOG IN button in the upper right corner of the page at the Bluemix homepage and enter your Bluemix ID and password on the authentication page that appears.

  2. View the available services: Click the USE SERVICES OR APIS link on the Services & APIs tile that appears near the top of the page.

    Bluemix Services & APIs tile
  3. Select the AlchemyAPI service: Click the tile for the AlchemyAPI service, which gives you access to the AlchemyLanguage and AlchemyData News APIs.

  4. Configure the instance that you are creating (Optional): You can optionally change the space in which the service will be instantiated, the name of the instance that you are creating, the billing plan that will be associated AlchemyAPI service, and so on.

  5. Create a service instance: Click CREATE at the right of the page to create an instance of the AlchemyAPI service.

  6. View and record your credentials: Click the Service Credentials link in the list of contents on the left of the page to view your Bluemix credentials. Save the value of the url and apikey fields. You will need to specify those in your AlchemyLanguage applications.

If you plan to develop your application outside of Bluemix, you are now done using the Bluemix interface and can close the browser page in which you are working.

Getting and installing cURL

You will only need to install curl if it is not already available on your system and you are working through the REST API examples in the Tutorials section of this documentation or on the cURL tab of the AlchemyLanguage API reference.

To check whether the cURL command is installed on your system, enter curl --version at a command prompt:

  1. If you see a response that includes a version number, the cURL command is installed on your system, and no further actions are required to use it.

  2. If you see a response like "curl: command not found" or "'curl' is not recognized as an internal or external command", you will need to install the cURL command on your system. To do so, use the Download Wizard to easily install the right version of cURL for your system. Make sure that you install the SSL-enabled version of cURL.