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:
- 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.
- 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" }
- 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:
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:
| 200 OK
| Request has been successfully processed, no error.
|
| 400 Bad Request
| Some parameter is missing or value not specified properly. Check if required parameters are specified.
|
| 401 Unauthorized
| API key is missing or authenticated user does not have permissions to call the method.
|
| 404 Not Found
| Resource does not exist. Check URL and resource name (id) if in URL.
|
| 405 Method Not Allowed
| Calling method with GET but the method only supports POST verb? Check the Allow header for available verbs.
|
| 500 Internal Server Error
| Internal error occurred on a server. Please notify us so we can fix the problem.
|
| 503 Service Unavailable
| Website or web service is under maintenance. Check the Retry-After header and try again later.
|
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
Samples
- Avivo Tech Blog contains some code to copy-paste for C#, Java, JavaScript, Python and PHP