Skip to content

Commit ccbb710

Browse files
author
baleine
committed
Markdown documentation for the QR Code Model
1 parent 74735f6 commit ccbb710

File tree

1 file changed

+315
-0
lines changed

1 file changed

+315
-0
lines changed

‎QR_Code_Model.md

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
FORMAT: 1A
2+
3+
# QR Code Model
4+
5+
This document describes the JSON model to use for Unitag's QR Code API.
6+
7+
## JSON model
8+
9+
Below is the global structure of a JSON object representing a QR Code:
10+
11+
```json
12+
{
13+
"content":
14+
{
15+
...
16+
},
17+
"design":
18+
{
19+
...
20+
},
21+
"owner":"20"
22+
}
23+
```
24+
25+
+ `owner` is used to match an existing user in the PostgreSQL database.
26+
+ `content` defines what is encoded in the QR Code.
27+
+ `design` defines the graphical properties of the QR Code.
28+
29+
### Content object
30+
31+
The content object defines the data encoded in the QR Code and can only be one of the following types: TEXT, URL, CALL, GEOLOC, SMS, WIFI, VCARD, EMAIL, EMAIL, CALENDAR, CALL.
32+
33+
#### TEXT
34+
```json
35+
{
36+
"type":"TEXT",
37+
"text":"Hello World"
38+
}
39+
```
40+
#### URL
41+
```json
42+
{
43+
"type":"URL",
44+
"url":"http://www.unitag.io"
45+
}
46+
```
47+
#### GEOLOC
48+
```json
49+
{
50+
"type":"GEOLOC",
51+
"geoloc":
52+
{
53+
"latitude":"43-36-16.2N",
54+
"longitude":"1-26-38.4E"
55+
}
56+
}
57+
```
58+
#### SMS
59+
```json
60+
{
61+
"type":"SMS",
62+
"sms":
63+
{
64+
"tel":"+33970805343",
65+
"message":"Hello World"
66+
}
67+
}
68+
```
69+
#### WIFI
70+
```json
71+
{
72+
"type":"WIFI",
73+
"wifi":
74+
{
75+
"security":"WPA",
76+
"ssid":"unitag_WIFI",
77+
"password":"your_password_here"
78+
}
79+
}
80+
```
81+
#### VCARD
82+
```json
83+
{
84+
"type":"VCARD",
85+
"vcard":
86+
{
87+
"firstname":"Romain",
88+
"lastname":"Kassel",
89+
"emailwork":"[email protected]",
90+
"emailhome":"[email protected]",
91+
"telcell":"+33970805341",
92+
"telwork":"+33970805342",
93+
"telhome":"+33970805343",
94+
"telfax":"+33970805344",
95+
"website":"http://www.unitag.io",
96+
"title":"CIO",
97+
"organization":"Unitag",
98+
"address":"67 allées Jean Jaurès",
99+
"postalcode":"31000",
100+
"city":"Toulouse",
101+
"country":"France"
102+
}
103+
}
104+
```
105+
#### EMAIL
106+
```json
107+
{
108+
"type":"EMAIL",
109+
"email":
110+
{
111+
"to":"[email protected]",
112+
"cc":"[email protected]",
113+
"bcc":"[email protected]",
114+
"subject":"test",
115+
"body":"Hello World"
116+
}
117+
}
118+
```
119+
#### CALENDAR
120+
```json
121+
{
122+
"type":"CALENDAR",
123+
"calendar":
124+
{
125+
"title":"AGM",
126+
"location":"Unitag - 67 allées Jean Jaurès 31000 Toulouse",
127+
"start":"10/02/2015 09:00",
128+
"end":"10/02/2015 12:00"
129+
}
130+
}
131+
```
132+
#### CALL
133+
```json
134+
{
135+
"type":"CALL",
136+
"call":
137+
{
138+
"phone":"+33970805343"
139+
}
140+
}
141+
```
142+
143+
### Design object
144+
145+
The design object contains all the graphical properties and modifications that define and can be applied to a QR Code image. Its structure is the following:
146+
```json
147+
{
148+
"owner":20,
149+
"color":"007FB6",
150+
"modules":
151+
{
152+
...
153+
},
154+
"eyes":
155+
{
156+
...
157+
},
158+
"logo":
159+
{
160+
...
161+
},
162+
"background":
163+
{
164+
...
165+
},
166+
"quietZone":true
167+
}
168+
```
169+
Fields `color`, `modules` and `eyes` are always mandatory, `owner` is only mandatory when persisting a design entity. By default there is no `logo`, no `background` and `quietZone` is set to true.
170+
171+
#### MODULES
172+
This object defines the graphical properties of the modules of a QR Code.
173+
```json
174+
{
175+
"shape":"DRIFTED",
176+
"roundness":"5",
177+
"correctionLevel":"M",
178+
"image":
179+
{
180+
"url":"https://static-unitag.com/file/freeqr/671f9c9974bf42694ee4eca41be358b5.jpg",
181+
"enlightment":"60.7987",
182+
"contrast":"0.58"
183+
},
184+
"gradient":
185+
{
186+
"color":"c41200",
187+
"type":"RAD_CYC",
188+
"x1":"50",
189+
"y1":"50",
190+
"radius":"30"
191+
}
192+
}
193+
```
194+
+ `shape` is mandatory and defines the shape applied to all the QR Code modules. Possible values are: NORMAL, ROUNDED, ROUNDED_LIGHT, ROUNDED_MEDIUM, ROUNDED_STRONG, SHAKED, DISTORTED, MELTED, DOTS, ARROWS, CURVED, DRIFTED, TICTACTOE, CIRCUIT_BOARD, CRYSTAL.
195+
+ `roundness` can be used to specify the rounded effect strength of the ROUNDED shape. Use integer values between 0 and 10. No need to specify a roundness value for shapes ROUNDED_LIGHT, ROUNDED_MEDIUM and ROUNDED_STRONG since they come with a default value.
196+
+ `correctionLevel` is also mandatory and specifies the correction level to use when creating the QR Code. With a high correction level, more modules are needed to encode the same data. Possible values are: L (low), M (medium), Q (quartile), H (high).
197+
+ `gradient` defines a color gradient that can be applied to the QR Code modules (see section below).
198+
+ `image` indicates an image to be overlayed on the the QR Code modules (see section below).
199+
200+
Warning: do not specify a gradient and an image at the same time.
201+
202+
##### GRADIENT
203+
Available fields to define a gradient are:
204+
```json
205+
{
206+
"color":"C41200",
207+
"type":"LIN_ACY",
208+
"x1":"0",
209+
"y1":"0",
210+
"x2":"250",
211+
"y2":"250"
212+
"radius":"20"
213+
}
214+
```
215+
+ `color` is the second color used to create the color gradient (the first one being the main design color). This field is mandatory
216+
+ `type` defines the color gradient type. This field is mandatory and all possible values are listed below.
217+
+ `x1` and `y1` are coordinates (from the top left corner) used to specify a starting point when needed for some of the gradients
218+
+ `x2` and `y2` are coordinates (from the top left corner) used to specify a second point when needed for some of the gradients
219+
+ `radius` is needed for some of the gradients
220+
221+
Different `type` values are available:
222+
+ HORI defines a horizontal gradient
223+
+ VERT defines a vertical gradient
224+
+ DIAG1 defines a gradient along the first QR Code diagonal
225+
+ DIAG2 defines a gradient along the second QR Code diagonal
226+
+ RAD defines a radial gradient from the center of the QR Code
227+
+ LIN_ACY defines a linear gradient (needs 2 points)
228+
+ LIN_CYC defines a cyclic linear gradient (needs 2 points)
229+
+ RAD_ACY defines a radial gradient (needs a center point and a radius)
230+
+ RAD_CYC defines a cyclic radial gradient (needs a center point and a radius)
231+
232+
##### IMAGE
233+
Available fields to define an image are:
234+
```json
235+
{
236+
"url":"https://static-unitag.com/file/freeqr/671f9c9974bf42694ee4eca41be358b5.jpg",
237+
"brightness":"60.7987",
238+
"contrast":"0.58"
239+
}
240+
```
241+
+ `url` is the only mandatory field. It should contain a URL where the image can be found. If the URL is invalid or if the image can't be read, the default background color will be used instead.
242+
+ `brightness` defines the image brightness (use positive values to brighten the image and negative values to darken it, we recommend using values between -100.0 and 100.0 where the changes are most visible)
243+
+ `contrast` defines the image contrast (positive values expected, we recommend using values between 0.0 and 2.0 where the changes are most visible)
244+
245+
#### EYES
246+
This object defines the graphical properties of the 3 eyes of a QR Code.
247+
```json
248+
{
249+
"shape":"SPIKE",
250+
"innerColor":"007FB6",
251+
"outerColor":"CC0099",
252+
"topRight":
253+
{
254+
"innerColor":"8A9935"
255+
},
256+
"topLeft":
257+
{
258+
"innerColor":"8A9935",
259+
"outerColor":"C41200"
260+
},
261+
"bottom":
262+
{
263+
"outerColor":"C41200"
264+
}
265+
}
266+
```
267+
+ `shape` is the only mandatory field and defines the shape of the eyes. Possible values are: DIAMOND, CIRCLE, CIRCLE_ROUNDED, ROUNDED, CURVED, CIRCLE_SQUARE, LEAVES_TL, LEAVES_TR, SPIKE_TL, SPIKE_TR, SPIKE_BL, SPIKE_BR, SPIKE, SHIELD, STAR, ROUNDEDSTAR, CURVEDSTAR, NORMAL, SHAKED, DOTS, DISTORTED, WAVE, TICTACTOE, OCTOGON, ALIEN and GRID.
268+
+ `innerColor` defines the color to use for the inner part of an eye (defaulted to the design's global color).
269+
+ `outerColor` defines the color to use for the outer part of an eye (defaulted to the design's global color).
270+
+ `topRight` is used to overwrite the color values for the top right eye.
271+
+ `topLeft` is used to overwrite the color values for the top left eye.
272+
+ `bottom` is used to overwrite the color values for the bottom eye.
273+
274+
#### LOGO
275+
Use the `logo` object to add an image on the QR Code.
276+
277+
Structure:
278+
```json
279+
{
280+
"url":"https://static-unitag.com/file/freeqr/671f9c9974bf42694ee4eca41be358b5.jpg",
281+
"width":"0.2",
282+
"height":"0.2",
283+
"leftOffset":"0.4",
284+
"topOffset":"0.6",
285+
"excavate":"true"
286+
}
287+
```
288+
289+
+ `url` is the only mandatory field. It should contain a URL where the logo image can be found. By default the logo is placed at the center of the image and `excavate` is set to true.
290+
+ `width` is used to specify the width of a logo when not using the default positioning. It works like a percentage of the QR Code image width.
291+
+ `height` is used to specify the height of a logo when not using the default positioning. It works like a percentage of the QR Code image height.
292+
+ `leftOffset` is used to specify where to place the logo from the left edge when not using the default positioning. It works like a percentage of the QR Code image width.
293+
+ `topOffset` is used to specify where to place the logo from the top edge when not using the default positioning. It works like a percentage of the QR Code image height.
294+
+ `excavate` tells the generator whether to remove the QR Code modules behind the logo. If set to true (by default), the modules behind the logo are removed and this makes the QR Code look better. If set to false, the logo is simply placed on the QR Code but can partially hide some of the modules.
295+
296+
#### BACKGROUND
297+
`background` can be set to either define a background color or a shadow.
298+
299+
Background color:
300+
```json
301+
{
302+
"color":"FFCC00"
303+
}
304+
```
305+
QR Code shadow:
306+
```json
307+
{
308+
"shadow":
309+
{
310+
"color":"BDBDBD",
311+
"strength":"M"
312+
}
313+
}
314+
```
315+
There are 3 different values for the field `strength` field which defines the strength of the shadow: `L` (light), `M` (medium), `S` (strong).

0 commit comments

Comments
 (0)