Generate QR Codes using API

Introduction

Esponce API offers you a way to integrate QR Code features into your application. API can be used in your application to automate generating QR Codes or decode content from scanned QR Code images or to handle trackable QR Codes and campaigns. This technical documentation describes how to use API 3.0 based on REST web service.

Improvements

API 3 adheres to REST guidelines and offers more features than previous versions. API 2 is still available but we recommend that you use the latest API version.

Ask a question?

API is in beta stage. If you have any questions please visit feedback or use Twitter @esponcetag

Quick start

To get familiar with API try the following examples:

1. To generate a QR Code make an HTTP GET request to http://www.esponce.com/api/v3/generate?content=hello&format=png where "hello" will be encoded in a QR Code. This method can be tested directly in a web browser.
2. To decode the content behind a QR Code image make an HTTP POST request to http://www.esponce.com/api/v3/decode and upload raw image bytes in the request. Server will return a message from the image, like { content: "some message" }
3. To get a list of campaigns and trackable QR Codes make a GET request to http://www.esponce.com/api/v3/track/list?auth=demo where the parameter auth should be your API key.

Libraries

Check out the libraries and samples to speed up integration.

API methods

All service method calls start with the base URL http://www.esponce.com/api/v3/ then follows a method name. Each method expects certain input parameters and returns a specific result. Details for each method are described further in the documentation.

General

generate	generate a QR Code image, using HTTP GET
decode	get content from QR Code image

QR Code Tracking

The following methods require API key to identify user:

track/list	get a list of campaigns and trackable QR Codes
track/campaign	manage campaign: select, insert, update, delete
track/qrcode	manage trackable QR Code: select, insert, update, delete
track/statistics	get statistics about a particular QR Code
track/export	export campaigns and trackable QR Codes
track/import	import campaigns and trackable QR Codes

Example

• URL to generate a QR Code: http://www.esponce.com/api/v3/generate
• URL to get a tracking list: http://www.esponce.com/api/v3/track/list
  

API structure

API follows the REST guidelines: uses GET, POST, PUT and DELETE verbs, uses friendly names in URL, responds with appropriate HTTP status code, supports JSON and XML formats, etc.

Parameters

GET and DELETE methods expects parameters only in URL. POST and PUT methods accepts combined parameters in both HTTP body and/or URL query depending on the context. Request parameters in URL must be present as key-value pairs where values are URL encoded.

Some parameters are required while others are optional. If required parameter is missing HTTP responds with status code 400 Bad Request. If an optional parameter is not set it automatically gets the default value.

Variable types

bool	true/false value
int	32-bit integer
double	decimal number
string	UTF-8 string in JSON/XML or URL encoded string in URL query
date	date formatted as "yyyy-MM-dd", e.g. "2012-01-05" for 5th January 2012
timestamp	date and time formatted as "yyyy-MM-ddTHH:mm:ssZ" (ISO 8601)
color	ARGB color, e.g. "#7FFFF500" for semi-transparent yellow
array	array of int, string, object or other types
object	custom type, additionally described in the documentation

Error handling

Errors are reported as HTTP status code: HTTP response may also contain a custom HTTP header X-Api-Error with a detailed error message for developer.

Secure connection

To use a secure HTTPS connection just replace http with https in base URL, i.e. https://www.esponce.com/api/v3

Authentication

Some methods require authentication to identify the caller. You will need an API key for authentication (get it at your profile page).

API key is passed as auth parameter in URL query, e.g. http://www.esponce.com/api/v3/track/list?auth=9b02ec5da819ff14450c56583211eff3

Warning: try not to use API key in public as malicious users can copy your API key and abuse it (e.g. unwanted delete or content change)

Data formats

In general methods can handle user-preferred JSON (application/json) or XML (application/xml) while import/export methods support CSV, XLS, XML, ZIP formats.

Data format is defined in Accept header, e.g. request with Accept: application/json returns data formatted as JSON while Accept: application/xml returns XML data. Default content type is JSON in case Accpet header is missing.

Limitations

Each user can generate up to 1.000 codes per day and can scan up to 200 codes.

Additional notes

• character encoding: UTF-8
• all dates and times are considered by UTC time zone
• domain qrcode.good-survey.com is still available but it is recommended to use www.esponce.com alias instead

Libraries and Samples

Libraries

• C# .NET 3.5 library and samples hosted on CodePlex
• PHP library and samples hosted on GitHub

Samples

• Avivo Tech Blog contains some code to copy-paste for C#, Java, JavaScript, Python and PHP