ShotCode.com API - Version 1.0
Last Update: November 14, 2007
In order to allow an easy and smooth integration with third-party sites and tools, ShotCode.com provides an easy to use XML Rest API that can handle several common scenarios - handling referrals, discovering and downloading the mobile client, etc.
Overview
ShotCode's API s composed by a series of services - each one of these endpoints accepts/expects a series of parameters,
and they all respond to http calls with an XML result.
Some of the services are plain usable by anyone and don't require any kind of signature or encrypted connection to work: that's the case of the
download endpoint. Others, however, require the usage of a specific API Key and can only be called over an HTTPS connection.
These specific services will be called "signed" from now on, whereas the open ones are known as "unsigned".
Adding ShotCodes to your website
Integrating ShotCode with any site is very easy: all you have to do
is supplying the desired site's URL (Internet address), and a ShotCode will be
generated automatically. Suppose you want a ShotCode that connects to
www.google.com:
To generate/show that ShotCode on a web page, simply put together a <img> tag like this:
<img src="http://www.shotcode.org/code.png?url=www.google.com" />
And the ShotCode will be shown (you can adjust the height and width using CSS or plain HTML width/height directives).
Note that one given URL will always generate the same ShotCode, so it is
granted that, in our example, www.google.com will always be represented by the same
ShotCode.
API Keys
In order to use ShotCode's signed services, it's necessary to have a Reseller account setup, and an API Key must be generated. Your API key is shown under the Account Settings page, just below your profile. That code must always be passed in as an HTTP POST parameter named api_key.
Calling ShotCode Services
Each Service is represented by a single URL with the following format: http://www.shotcode.com/services/v<version>/<service name> (note that signed services
start with https:// instead of http://). Whenever a service specifies that it requires parameters, it is refering to regular HTTP request parameters
Any API call must be done using HTTP POST.
To illustrate all that, if this documentation specifies a signed service called statistics which
expects code_id and month as parameters, it's endpoint would be https://www.shotcode.com/services/v1/statistics and three HTTP POST parameters were to be expected: code_id, month and api_key (it is a signed service, remember that?).
Similarly, an unsigned ping service that requires a user parameter could be called via http://www.shotcode.com/services/v1/ping and have the user attribute passed as a request parameter.
The specific parameters and endpoint for each service are detailed on its own documentation page.
The response to API calls always returns a valid XML document. The root element of the XML is named after the service (a ping service will return an XML starting with <ping>). The exact content of the response varies - check the specific service documentation
for a complete guideline.
Unsigned Services
Download - an endpoint used to retrieve a full list of phones that support ShotCode Reader, and the download URL for themSigned Services
Signup - a reseller integration serviceShotcodes Listing - an endpoint to manage your account's shotcodes
Create Shotcode - an endpoint that allows creation of new shotcodes on your account
Decode Shotcode - an endpoint that allows decoding of a shotcode to retrieve the embedded url