tagSOLUTE API Tutorial

Getting started

In order to get you started as quickly as possible, we're providing code samples for the most common programming languages that will get you on the road within minutes.

Our code samples all have a similar directory/file structure.

  • a config file

    containing the definition of your API URL and DevKey

  • an API file

    containing helper methods for accessing the API

  • an example file

    containing sample code on how to use the helper methods

  • a JSON library directory

    containing the JSON library files

In order to try the samples, you just need to:

  • download and extract the archive file provided in the section of your desired programming language
  • register on our site to get your personal development key
  • modify the config file appropriately
  • run the example file

Once you've verified that the example file runs without problems, you can then dig deeper into our API documentation and start coming up with ideas of your own applications using the latest mobile tagging technology.

Limitations

Please note that our regular development keys are limited to 300 tag creations (not including cache hits). Should you happen to exceed your limit and need more feel free to contact us, so we can work out the details.

Supported Languages

We are currently providing sample code for:

PHP

Archive

The archive of the PHP sample code can be downloaded below:

  • php.zip (MD5: acd41859b3f5f9e0b47bebb281601fd6)

Instructions

  • Unzip the archive to a directory of your choice.

  • Update config.php with your developer key

    <?php

	define("TAGSOLUTE_DEV_KEY", "<enter your DevKey here>");
	define("TAGSOLUTE_API_URL", "http://www.tagsolute.de/cgi-bin/api.cgi");

?>

  • If you're not running PHP 5.2, uncomment the following line in example.php to include the JSON library

    //require_once("json/JSON.php");

  • Run example.php from the command line, i.e.:

    php example.php

  • If the example API call is successful, the output should look something like this:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • If instead the call fails, you'll see the error message, i.e.:

    Dev-Key '<enter your DevKey here>' could not be found.

    NOTE: Please make sure you use PHP's default value of "&" for the arg_separator.output php.ini parameter - using a value of "&amp;" (which some installations of XAMPP on Windows ship with) may lead to an ApiCallArgumentListError, because our scripts will detect an additional and unsupported "amp" parameter.

Sample Code

The required code to make the API call can be found in example.php

<?php

	require_once("api.php");
	
	// uncomment the following line and point the require_once to your JSON library, if you use PHP<5.2
	//require_once("json/JSON.php");
	
	$mParams = array("sText" => "Hello, world!");
	
	// call the method
	$mResult = mxApiCall("GetTextTag", $mParams);
	
	if($mResult["bSuccessful"]) {
		print $mResult["jResult"];
	}
	else {
		print $mResult["jResult"]["sInfo"];
	}

	print "\n";
?>

JavaScript

Archive

The archive of the JavaScript sample code can be downloaded below:

  • js.zip (MD5: dd7b69b6fd02c025990892cb61fbba42)

Instructions

  • Unzip the archive to a directory of your choice.

  • Update config.js with your developer key

    var TAGSOLUTE_DEV_KEY = "<enter your DevKey here>";
var TAGSOLUTE_API_URL = "http://www.tagsolute.de/cgi-bin/api.cgi";

  • Open example.html in your favorite browser

  • If the example API call is successful, the content of the input field should change to something like this:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • If instead the call fails, you'll see the error message, in the input field, i.e.:

    Dev-Key '<enter your DevKey here>' could not be found.

Sample Code

The required code to make the API call can be found in example.html

<html>
	<head>
		<title>tagSOLUTE JavaScript/AJAX API Call Sample</title>

		<script type="text/javascript" src="config.js"></script>
		<script type="text/javascript" src="http://theurer.cc/code/jsonSamples/jsr_class.js"></script>
		<script type="text/javascript" src="api.js"></script>
		
		<script language="javascript">

			function vxHelloWorld() {
			
				/* Call our the GetTextTag API method to generate a tag containing the text "Hello, world!".
				 *
				 * Arguments:
				 * 	None
				 *
				 * Returns:
				 *     Nothing
				 */
			
				mParams = new Object();
				mParams.sMethod = "GetTextTag";
				mParams.sText = "Hello, world!";
			
				vxApiCall(TAGSOLUTE_DEV_KEY, TAGSOLUTE_API_URL, mParams, vxShowResponse);
			
			}
			
			function vxShowResponse(pResponse) {
			
				/* Show the content of the request.
				 *
				 * Arguments:
				 *     pResponse -- the API response
				 *
				 * Returns:
				 *     Nothing
				 */
			
			
				if (pResponse["bSuccessful"]==true) {
					document.getElementById("wdgDebug").value = pResponse["jResult"];
				}
				else {
					alert(pResponse["jResult"]["sInfo"]);
				}
			}

		</script>

	</head>
	<body onload="vxHelloWorld()">

		URL of "Hello, world!" tag image:<br/>
		<input type="text" id="wdgDebug" style="width:600px;"/>

	</body>
</html>

HTML

Archive

The archive of the HTML sample code can be downloaded below:

  • html.zip (MD5: d6a2e9e83a41b77ffec9a79e1bb47aaa)

Instructions

  • Unzip the archive to a directory of your choice.

  • Update example.html with your developer key

    <html>
	<body>
		<img src="http://www.tagsolute.de/cgi-bin/api.cgi?sDevKey=<enter your DevKey here>&sMethod=GetTextTag&sText=Hello,world!"/>
	</body>
</html>

  • Open example.html in your favorite browser

  • If the example API call is successful, you'll see the tag image in your browser window.

  • If instead the call fails, you'll see the a static tag image with the string "ERROR" in the center.

Java

Archive

The archive of the Java sample code can be downloaded below:

  • java.zip (MD5: 779e18b17f57d18901785274d4f5a012)

Instructions

  • Unzip the archive to a directory of your choice.

  • Update Config.java with your developer key

    public final class Config {

	public static String TAGSOLUTE_DEV_KEY = "<enter your DevKey here>";
	public static String TAGSOLUTE_API_URL = "http://www.tagsolute.de/cgi-bin/api.cgi";

}

  • Compile Example.java, i.e.

    javac -cp .;json Example.java

    NOTE: If you compile with a JDK version higher than 1.4, you'll receive a compilation warning about the unchecked Hashmap we're using in our sample code. This has to do with the fact, that we're not strongly typing the arguments, we're sending off via HTTP. But since the typing will get lost during URL encoding anyway, we don't need it. So you can safely ignore the warning.

    Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

  • Run Example.class, i.e.

    java -cp .;json Example

  • If the example API call is successful, the output should look something like this:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • If instead the call fails, you'll see the error message, i.e.:

    Dev-Key '<enter your DevKey here>' could not be found.

Sample Code

The required code to make the API call can be found in Example.java

import java.util.HashMap;

import org.json.JSONException;
import org.json.JSONObject;

public class Example {

	public static void main(String[] aArgs) {
		
		HashMap mParams = new HashMap();
		mParams.put("sText", "Hello, world!");
		
		try {
			Api pApi = new Api();

			JSONObject pResponse = pApi.pxApiCall("GetTextTag", mParams);

			if (pResponse.getBoolean("bSuccessful")) {

				String sTagImageUrl = pResponse.getString("jResult");
				System.out.println(sTagImageUrl);

			}
			else {

				String sInfo = pResponse.getJSONObject("jResult").getString("sInfo");
				System.out.println(sInfo);

			}
		
		}
		catch(JSONException pException) {
			System.out.println("Error: " + pException.getLocalizedMessage());
		}
		
	}
	
}

Python

Archive

The archive of the Python sample code can be downloaded below:

  • python.zip (MD5: f391e6a1b9127a5c733e29b64d463416)

Instructions

  • Unzip the archive to a directory of your choice.

  • Update config.py with your developer key

    TAGSOLUTE_DEV_KEY = "<enter your DevKey here>";
TAGSOLUTE_API_URL = "http://www.tagsolute.de/cgi-bin/api.cgi";

  • Run example.py, i.e.

    python example.py

  • If the example API call is successful, the output should look something like this:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • If instead the call fails, you'll see the error message, i.e.:

    Dev-Key '<enter your DevKey here>' could not be found.

Sample Code

The required code to make the API call can be found in example.py

import api
        
mParams = {"sText": "Hello, world!"}

pResponse = api.mxApiCall("GetTextTag", mParams)

if pResponse["bSuccessful"]:
    print pResponse["jResult"]
else:
    print pResponse["jResult"]["sInfo"]

C#

Archive

The archive of the C# sample code can be downloaded below:

  • cs.zip (MD5: 6a9b8236515c3f53ce4652e0383a3123)

Instructions

  • Unzip the archive to a directory of your choice.

  • Update Config.cs with your developer key

    namespace tagSOLUTE {
	
	class Config 
	{
		public static string TAGSOLUTE_DEV_KEY = "<enter your DevKey here>";
		public static string TAGSOLUTE_API_URL = "http://www.tagsolute.de/cgi-bin/api.cgi";
	}
}

  • Compile Example.cs, i.e.

    csc /r:json\Bin\Newtonsoft.Json.dll Api.cs Config.cs Example.cs

  • Run Example.class, i.e.

    Example.exe

    NOTE: Make sure Newtonsoft.Json.dll (from json/Bin) is in your PATH when deploying and executing the EXE file, otherwise you'll get an error similar to this one:

    Unhandled Exception: System.IO.FileNotFoundException: Could not load file or assembly 'Newtonsoft.Json, Version=1.3.0.0, Culture=neutral, PublicKeyToken=null' or one of its dependencies. Das System kann die angegebene Datei nicht finden.
File name: 'Newtonsoft.Json, Version=1.3.0.0, Culture=neutral, PublicKeyToken=null'
   at Example.Main(String[] aArgs)

WRN: Assembly binding logging is turned OFF.
To enable assembly bind failure logging, set the registry value [HKLM\Software\Microsoft\Fusion!EnableLog] (DWORD) to 1.
Note: There is some performance penalty associated with assembly bind failure logging.
To turn this feature off, remove the registry value [HKLM\Software\Microsoft\Fusion!EnableLog].

  • NOTE: In case you get the error below, you are probably launching the EXE from a network drive. Try launching it from a local drive to see if that fixes the error.

    Error: System.Security.SecurityException: Request for the permission of type 'System.Net.WebPermission, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089' failed.
   at System.Security.CodeAccessSecurityEngine.Check(Object demand, StackCrawlMark& stackMark, Boolean isPermSet)
   at System.Security.CodeAccessPermission.Demand()
   at System.Net.HttpWebRequest..ctor(Uri uri, ServicePoint servicePoint)
   at System.Net.HttpRequestCreator.Create(Uri Uri)
   at System.Net.WebRequest.Create(Uri requestUri, Boolean useUriBase)
   at System.Net.WebRequest.Create(String requestUriString)
   at tagSOLUTE.Api.sxGetUrlContent(String sUrl, Hashtable mParams)
The action that failed was:
Demand
The type of the first permission that failed was:
System.Net.WebPermission
The Zone of the assembly that failed was:
Internet

  • If the example API call is successful, the output should look something like this:

    http://www.tagsolute.de/tag/a8128f20272c8affb367b62d2f509aeb

  • If instead the call fails, you'll see the error message, i.e.:

    Dev-Key '<enter your DevKey here>' could not be found.

Sample Code

The required code to make the API call can be found in Example.cs

using System;
using System.Collections;
using tagSOLUTE;
using Newtonsoft.Json;

class Example {

	public static void Main(string[] aArgs) {

		Hashtable mParams = new Hashtable();
		mParams.Add("sText", "Hello, world!");

		Api pApi = new Api();
		
		JavaScriptObject pResponse = pApi.pxApiCall("GetTextTag", mParams);

		if((bool) pResponse["bSuccessful"]) {
			Console.WriteLine(pResponse["jResult"]);
		}
		else {
			JavaScriptObject pJResult = (JavaScriptObject) pResponse["jResult"];
			Console.WriteLine(pJResult["sInfo"]);
		}
		
    }
    
}