QR Code Generation API Documentation

The go-pdf service provides a comprehensive QR code generation endpoint that supports multiple QR code types including URLs, WiFi networks, contact information, events, geographic coordinates, and more.

Endpoint

POST /api/v1/qrcode

Request Format

Content-Type: application/json

Response: PNG image (image/png)

Request Body Structure

{
  "type": "string",        // Required: QR code type
  "content": "string",     // Main content (varies by type)
  "size": 256,             // Optional: Image size in pixels (64-2048, default: 256)
  
  // Type-specific fields
  "password": "string",     // For WiFi: network password
  "latitude": 0.0,         // For geo: latitude coordinate
  "longitude": 0.0,        // For geo: longitude coordinate
  "label": "string",       // For geo: location label/name
  
  // Contact fields (for vcard/mecard)
  "first_name": "string",
  "last_name": "string",
  "organization": "string",
  "phone": "string",
  "email": "string",
  "address": "string",
  "website": "string",     // For vcard only
  "note": "string",        // For vcard only
  
  // Event fields
  "summary": "string",     // Event title
  "description": "string", // Event description
  "location": "string",     // Event location
  "start_time": "string",  // Event start time (RFC3339 or YYYYMMDDTHHMMSS)
  "end_time": "string"    // Event end time (RFC3339 or YYYYMMDDTHHMMSS)
}

Supported QR Code Types

1. Text / Plaintext

Generate a QR code containing plain text.

Type: text or plaintext

Required Fields:

content: The text to encode

Example:

{
  "type": "text",
  "content": "Hello, World!",
  "size": 256
}

2. URL

Generate a QR code containing a URL. Automatically adds https:// if no scheme is provided.

Type: url

Required Fields:

content: The URL (e.g., "https://example.com" or "example.com")

Example:

{
  "type": "url",
  "content": "https://www.google.com",
  "size": 256
}

{
  "type": "url",
  "content": "example.com",
  "size": 256
}

3. WiFi Network

Generate a QR code that allows devices to connect to a WiFi network.

Type: wifi

Required Fields:

content: SSID (network name)
password: Network password (optional, if not provided, network is open)

Example:

{
  "type": "wifi",
  "content": "MyNetwork",
  "password": "MySecurePassword123",
  "size": 256
}

Open Network (No Password):

{
  "type": "wifi",
  "content": "PublicWiFi",
  "size": 256
}

4. Email

Generate a QR code that opens an email client with pre-filled recipient, subject, and body.

Type: email

Required Fields:

content or email: Email address

Optional Query Parameters:

subject: Email subject line
body: Email body text

Example:

{
  "type": "email",
  "content": "contact@example.com",
  "size": 256
}

With Subject and Body (via query parameters):

POST /api/v1/qrcode?subject=Hello&body=This%20is%20a%20test
Content-Type: application/json

{
  "type": "email",
  "content": "contact@example.com",
  "size": 256
}

5. SMS

Generate a QR code that opens the SMS app with a pre-filled phone number and message.

Type: sms

Required Fields:

content or phone: Phone number

Optional Query Parameters:

body: SMS message text

Example:

{
  "type": "sms",
  "content": "+1234567890",
  "size": 256
}

With Message:

POST /api/v1/qrcode?body=Hello%20from%20QR
Content-Type: application/json

{
  "type": "sms",
  "content": "+1234567890",
  "size": 256
}

6. Phone

Generate a QR code containing a phone number for dialing.

Type: phone

Required Fields:

content or phone: Phone number

Example:

{
  "type": "phone",
  "content": "+1234567890",
  "size": 256
}

7. vCard (Contact Card)

Generate a QR code containing contact information in vCard 3.0 format (RFC 6350).

Type: vcard

Required Fields:

At least one of: first_name, last_name, or content

Optional Fields:

first_name: First name
last_name: Last name
organization: Company/organization name
phone: Phone number
email: Email address
address: Physical address
website: Website URL
note: Additional notes

Example:

{
  "type": "vcard",
  "first_name": "John",
  "last_name": "Doe",
  "organization": "Example Corp",
  "phone": "+1234567890",
  "email": "john.doe@example.com",
  "address": "123 Main St, City, State 12345",
  "website": "www.example.com",
  "note": "VP of Engineering",
  "size": 256
}

Minimal vCard:

{
  "type": "vcard",
  "content": "John Doe",
  "email": "john@example.com",
  "size": 256
}

8. MeCard (Simplified Contact)

Generate a QR code containing contact information in MeCard format (simplified format used by many QR code readers).

Type: mecard

Required Fields:

At least one of: first_name, last_name, or content

Optional Fields:

first_name: First name
last_name: Last name
organization: Company/organization name
phone: Phone number
email: Email address
address: Physical address

Example:

{
  "type": "mecard",
  "first_name": "Jane",
  "last_name": "Smith",
  "organization": "Tech Inc",
  "phone": "+1234567890",
  "email": "jane@example.com",
  "address": "456 Oak Ave, City, State",
  "size": 256
}

9. Geographic Coordinates

Generate a QR code containing geographic coordinates that opens in a maps application.

Type: geo

Required Fields:

Either latitude and longitude, OR content as "latitude,longitude"

Optional Fields:

label: Location name/label

Example (using latitude/longitude fields):

{
  "type": "geo",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "label": "New York City",
  "size": 256
}

Example (using content field):

{
  "type": "geo",
  "content": "40.7128,-74.0060",
  "label": "Statue of Liberty",
  "size": 256
}

Without Label:

{
  "type": "geo",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "size": 256
}

10. Event (Calendar Event)

Generate a QR code containing a calendar event in iCalendar/VEVENT format.

Type: event

Required Fields:

summary or content: Event title

Optional Fields:

description: Event description
location: Event location
start_time: Start date/time (RFC3339, YYYYMMDDTHHMMSS, or YYYYMMDD)
end_time: End date/time (RFC3339, YYYYMMDDTHHMMSS, or YYYYMMDD)

Supported Date/Time Formats:

RFC3339: 2024-12-25T10:00:00Z or 2024-12-25T10:00:00-05:00
iCalendar: 20241225T100000 or 20241225T100000Z
Date only: 2024-12-25 or 20241225 (assumes 00:00:00)

Example:

{
  "type": "event",
  "summary": "Team Meeting",
  "description": "Monthly team sync meeting",
  "location": "Conference Room A",
  "start_time": "2024-12-25T10:00:00Z",
  "end_time": "2024-12-25T11:00:00Z",
  "size": 256
}

Simple Date Format:

{
  "type": "event",
  "summary": "Birthday Party",
  "location": "My House",
  "start_time": "20241225T180000",
  "end_time": "20241225T220000",
  "size": 256
}

11. Deep Link

Generate a QR code containing a deep link URL for mobile apps or web applications.

Type: deeplink

Required Fields:

content: Deep link URL (must include scheme, e.g., myapp://action or https://app.com/link)

Example:

{
  "type": "deeplink",
  "content": "myapp://profile/12345",
  "size": 256
}

Web Deep Link:

{
  "type": "deeplink",
  "content": "https://app.example.com/login?token=abc123",
  "size": 256
}

Response

Content-Type: image/png

Headers:

Content-Type: image/png
Content-Disposition: inline; filename=qrcode-{type}.png
X-QR-Type: The QR code type that was generated
X-Generated-At: Timestamp (RFC3339)

Body: PNG image bytes

Error Responses

400 Bad Request

Invalid request format or missing required fields.

{
  "error": "Content is required",
  "message": "The 'content' field cannot be empty for type: url"
}

500 Internal Server Error

Failed to generate QR code.

{
  "error": "Failed to generate QR code",
  "message": "Error details..."
}

Examples

Complete Examples with cURL

Text QR Code:

curl -X POST http://localhost:8080/api/v1/qrcode \
  -H "Content-Type: application/json" \
  -d '{"type":"text","content":"Hello World","size":256}' \
  -o qrcode-text.png

WiFi QR Code:

curl -X POST http://localhost:8080/api/v1/qrcode \
  -H "Content-Type: application/json" \
  -d '{"type":"wifi","content":"MyNetwork","password":"MyPassword123","size":256}' \
  -o qrcode-wifi.png

vCard QR Code:

curl -X POST http://localhost:8080/api/v1/qrcode \
  -H "Content-Type: application/json" \
  -d '{
    "type":"vcard",
    "first_name":"John",
    "last_name":"Doe",
    "email":"john@example.com",
    "phone":"+1234567890",
    "organization":"Example Corp",
    "size":256
  }' \
  -o qrcode-vcard.png

Geo Coordinates QR Code:

curl -X POST http://localhost:8080/api/v1/qrcode \
  -H "Content-Type: application/json" \
  -d '{
    "type":"geo",
    "latitude":40.7128,
    "longitude":-74.0060,
    "label":"New York City",
    "size":256
  }' \
  -o qrcode-geo.png

Event QR Code:

curl -X POST http://localhost:8080/api/v1/qrcode \
  -H "Content-Type: application/json" \
  -d '{
    "type":"event",
    "summary":"Team Meeting",
    "location":"Conference Room A",
    "start_time":"2024-12-25T10:00:00Z",
    "end_time":"2024-12-25T11:00:00Z",
    "size":256
  }' \
  -o qrcode-event.png

PowerShell Examples

Text QR Code:

Invoke-RestMethod -Uri "http://localhost:8080/api/v1/qrcode" `
  -Method Post `
  -ContentType "application/json" `
  -Body '{"type":"text","content":"Hello World","size":256}' `
  -OutFile "qrcode-text.png"

WiFi QR Code:

$body = @{
    type = "wifi"
    content = "MyNetwork"
    password = "MyPassword123"
    size = 256
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:8080/api/v1/qrcode" `
  -Method Post `
  -ContentType "application/json" `
  -Body $body `
  -OutFile "qrcode-wifi.png"

JavaScript/Fetch Examples

URL QR Code:

fetch('http://localhost:8080/api/v1/qrcode', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        type: 'url',
        content: 'https://www.example.com',
        size: 256
    })
})
.then(response => response.blob())
.then(blob => {
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'qrcode.png';
    a.click();
});

vCard QR Code:

fetch('http://localhost:8080/api/v1/qrcode', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        type: 'vcard',
        first_name: 'John',
        last_name: 'Doe',
        email: 'john@example.com',
        phone: '+1234567890',
        organization: 'Example Corp',
        size: 256
    })
})
.then(response => response.blob())
.then(blob => {
    const url = window.URL.createObjectURL(blob);
    const img = document.createElement('img');
    img.src = url;
    document.body.appendChild(img);
});

Notes

Size Limits: QR code size is limited between 64 and 2048 pixels. Default is 256 pixels.
URL Auto-completion: For url type, if no scheme is provided (http:// or https://), https:// is automatically prepended.
Date/Time Formats: The event type accepts multiple date/time formats for convenience, including RFC3339, iCalendar format, and simple date formats.
Field Flexibility: Many types support alternative fields. For example, email type can use either content or email field. phone type can use either content or phone field.
Query Parameters: Some types (like email and sms) support additional query parameters for URL-based features.
Encoding: Special characters in contact cards and events are automatically escaped according to their respective format specifications (vCard, MeCard, iCalendar).

Testing

Use the provided test scripts to test all QR code types:

# Linux/Mac
./test-qrcode.sh

# Windows PowerShell
.\test-qrcode.ps1

These scripts generate QR codes for all supported types and save them as PNG files.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

QR Code Generation API Documentation

Endpoint

Request Format

Request Body Structure

Supported QR Code Types

1. Text / Plaintext

2. URL

3. WiFi Network

4. Email

5. SMS

6. Phone

7. vCard (Contact Card)

8. MeCard (Simplified Contact)

9. Geographic Coordinates

10. Event (Calendar Event)

11. Deep Link

Response

Error Responses

400 Bad Request

500 Internal Server Error

Examples

Complete Examples with cURL

PowerShell Examples

JavaScript/Fetch Examples

Notes

Testing

FilesExpand file tree

QR_CODE_API.md

Latest commit

History

QR_CODE_API.md

File metadata and controls

QR Code Generation API Documentation

Endpoint

Request Format

Request Body Structure

Supported QR Code Types

1. Text / Plaintext

2. URL

3. WiFi Network

4. Email

5. SMS

6. Phone

7. vCard (Contact Card)

8. MeCard (Simplified Contact)

9. Geographic Coordinates

10. Event (Calendar Event)

11. Deep Link

Response

Error Responses

400 Bad Request

500 Internal Server Error

Examples

Complete Examples with cURL

PowerShell Examples

JavaScript/Fetch Examples

Notes

Testing