ActivateAuthenticateAmplify
API Reference
DashboardSupportDeveloper Blog

Redirections (legacy)

Redirections allow fixed physical barcodes and QR codes to point to dynamically changing locations on the web. Each redirection resource associates a Thng or product, with the full URL it will redirect to. Each redirection is automatically assigned a short ID, which combined with the chosen short URL domain produces the short URL.

For example, a redirection created for a Thng could have the short ID df8f76hd, in the tn.gg short URL domain, resulting in its short URL becoming https://tn.gg/df8f76hd. The redirection itself would instruct all visitors to that short URL to the full URL, such as https://brand.com/catalogue?product=UNwYkFVG9ef4wEwwap9XFqpn.

📘

Redirector

Using the Redirector service, rules including location, user data, action context, date/time, and more can be used to selectively redirect the user, enabling a more powerful experience. For example, a different web page to be returned for users in different countries, or during different days of the week.

See Resource Redirections for more conceptual information.

API Status
General Availability:
https://tn.gg/redirections (inc. other short domains)

Jump To ↓

RedirectionDocument Data Model
Create a Redirection
Read a Redirection
Update a Redirection
Delete a Redirection
Read all Redirections on a Thng
Generate a QR Code

RedirectionDocument Data Model

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.defaultRedirectUrl (string, required)
    The location to redirect to.

.redirectUrl (string)
    The redirect URL.

.evrythngUrl (string, read-only)
    The location of the EVRYTHNG resource.

.evrythngId (string, read-only)
    The EVRYTHNG ID of the associated resource.

.shortDomain (string, read-only)
    The associated short domain for the redirection.

.shortId (string, read-only)
    The short ID of the redirection

.type (string, read-only, one of 'thng', 'product', 'collection', 'place')
    The type of the associated EVRYTHNG resource.

.hits (integer, read-only)
    The number of times the redirection has been hit.

{
  "additionalProperties": false,
  "type": "object",
  "description": "A redirection on a resource.",
  "required": ["defaultRedirectUrl"],
  "properties": {
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "defaultRedirectUrl": {
      "type": "string",
      "description": "The location to redirect to."
    },
    "redirectUrl": {
      "type": "string",
      "description": "The redirect URL."
    },
    "evrythngUrl": {
      "type": "string",
      "description": "The location of the EVRYTHNG resource.",
      "readOnly": true
    },
    "evrythngId": {
      "type": "string",
      "description": "The EVRYTHNG ID of the associated resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "shortDomain": {
      "type": "string",
      "description": "The associated short domain for the redirection.",
      "readOnly": true
    },
    "shortId": {
      "type": "string",
      "description": "The short ID of the redirection",
      "minLength": 8,
      "maxLength": 10,
      "readOnly": true
    },
    "type": {
      "type": "string",
      "description": "The type of the associated EVRYTHNG resource.",
      "enum": ["thng", "product", "collection", "place"],
      "readOnly": true
    },
    "hits": {
      "type": "integer",
      "description": "The number of times the redirection has been hit.",
      "readOnly": true
    }
  }
}

{
  "createdAt": 1510919459418,
  "defaultRedirectUrl": "https://example.com?thng=UFqMRDbaqm8EEMRaRF5h7cEg",
  "evrythngId": "UFqMRDbaqm8EEMRaRF5h7cEg",
  "evrythngUrl": "https://api.evrythng.com/thngs/UFqMRDbaqm8EEMRaRF5h7cEg",
  "hits": 14,
  "redirectUrl": "https://example.com?thng=UFqMRDbaqm8EEMRaRF5h7cEg",
  "shortDomain": "tn.gg",
  "shortId": "GrqPQbvg",
  "type": "thng",
  "updatedAt": 1510919527219
}

Create a Redirection

📘

Thng and Product Redirections

It is possible to create a Thng or products' redirection directly on its resource. Read the Thngs and Products pages for more information.

To create a redirection for an EVRYTHNG resource it is required to specify the required parameter defaultRedirectUrl to be used as a full URL for each access of the short URL. This could be a brand experience, product information, or some other brand-defined web location.

🚧

Note

The default response is a QR code image representing the redirection, unless the accept request header is set to application/json.

POST https://tn.gg/redirections
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

RedirectionDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://tn.gg/redirections' \
  -d '{
    "defaultRedirectUrl":"https://museum.com/displayWorks/catalogue.php?catalogue_id={evrythngId}",
    "evrythngId":"UVpfh4EFsBpasUmnVDWdktKs",
    "type":"thng"
  }'

const thngId = 'UH4nVsWVMG8EEqRawkMnybMh';
const defaultRedirectUrl = 'https://example.com?thng={thngId}';

const payload = {
  evrythngId: thngId,
  defaultRedirectUrl,
  type: 'thng',
};

evrythng.api({
  apiUrl: 'https://tn.gg',
  url: '/redirections',
  method: 'post',
  apiKey: operatorApiKey,
  headers: { Accept: 'application/json' },
  data: payload,
}).then(console.log);

HTTP/1.1 201 Created
Content-type: application/json
Location: https://tn.gg/a3gZQXfF

{
  "createdAt":1434088921717,
  "updatedAt":1434088921717,
  "shortDomain":"tn.gg",
  "defaultRedirectUrl":"https://museum.com/displayWorks/catalogue.php?catalogue_id=UVpfh4EFsBpasUmnVDWdktKs",
  "redirectUrl":"https://museum.com/displayWorks/catalogue.php?catalogue_id=UVpfh4EFsBpasUmnVDWdktKs",
  "type":"thng",
  "evrythngUrl":"https://api.evrythng.com/thngs/UVpfh4EFsBpasUmnVDWdktKs",
  "shortId":"a3gZQXfF",
  "evrythngId":"UVpfh4EFsBpasUmnVDWdktKs",
  "hits":0
}

Read a Redirection

Read a redirection to obtain information about the Thng associated with it. You can also read a short domain URL, for example: GET https://tn.gg/:shortId.

📘

Note

To be able to read the JSON metadata for the redirection, make sure to set the Accept header to application/json.

GET https://tn.gg/redirections/:shortId
Authorization: $OPERATOR_API_KEY
Accept: application/json

curl -H "Authorization: $OPERATOR_API_KEY" \
  -H "Accept: application/json"
  -X GET 'https://tn.gg/redirections/a3gZQXfF'

const thngId = 'UVpfh4EFsBpasUmnVDWdktKs';

evrythng.api({
  apiUrl: 'https://tn.gg',
  url: `/redirections?evrythngId=${thngId}`,
  headers: { Accept: 'application/json' },
  apiKey: operatorApiKey,
}).then(console.log);

HTTP/1.1 200 OK
Content-type: application/json

{
  "createdAt": 1434088921717,
  "updatedAt": 1434091515411,
  "shortDomain": "tn.gg",
  "defaultRedirectUrl": "https://museum.com/displayWorks/catalogue.php?catalogue_id=UVpfh4EFsBpasUmnVDWdktKs",
  "redirectUrl": "https://museum.com/displayWorks/catalogue.php?catalogue_id=UVpfh4EFsBpasUmnVDWdktKs",
  "type": "thng",
  "evrythngUrl": "https://api.evrythng.com/thngs/UVpfh4EFsBpasUmnVDWdktKs",
  "shortId": "a3gZQXfF",
  "evrythngId": "UVpfh4EFsBpasUmnVDWdktKs",
  "hits": 347
}

Update a Redirection

Submit a new set of redirection information to dynamically change where the short ID will send the user.

PUT https://tn.gg/redirections/:shortId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

RedirectionDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://tn.gg/redirections/a3gZQXfF' \
  -d '{
    "defaultRedirectUrl": "https://museum.com/displayWorks/catalogue.php?catalogue_id=:evrythngId"
  }'

const thngId = 'UH4nVsWVMG8EEqRawkMnybMh';
const defaultRedirectUrl = 'https://example.com?thng={thngId}';

const payload = {
  evrythngId: thngId,
  defaultRedirectUrl,
};

evrythng.api({
  apiUrl: 'https://tn.gg',
  url: '/redirections',
  method: 'put',
  apiKey: operatorApiKey,
  headers: { Accept: 'application/json' },
  data: payload,
}).then(console.log);

HTTP/1.1 200 OK
Content-type: application/json

{
  "createdAt": 1434088921717,
  "updatedAt": 1434091515411,
  "shortDomain": "tn.gg",
  "defaultRedirectUrl": "https://example.com?thng=UVpfh4EFsBpasUmnVDWdktKs",
  "redirectUrl": "https://example.com?thng=UVpfh4EFsBpasUmnVDWdktKs",
  "type": "thng",
  "evrythngUrl": "https://api.evrythng.com/thngs/UVpfh4EFsBpasUmnVDWdktKs",
  "shortId": "a3gZQXfF",
  "evrythngId": "UVpfh4EFsBpasUmnVDWdktKs",
  "hits": 481
}

Delete a Redirection

Delete a redirection. After this operation, the short link will no longer work.

DELETE https://tn.gg/redirections/:shortId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://tn.gg/redirections/a3gZQXfF'

HTTP/1.1 200 OK

Read all Redirections on a Thng

List all redirections associated to EVRYTHNG resource. The main parameter is evrythngId, the ID of the resource possessing the redirection. Multiple redirections can be added to a single resource by making multiple redirection creation requests.

GET https://tn.gg/redirections?evrythngId=:evrythngId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://tn.gg/redirections?evrythngId=UVpfh4EFsBpasUmnVDWdktKs'

The output is an array of redirections associated with the resource. 

HTTP/1.1 200 OK
Content-type: application/json

[
  {
    "createdAt":1434088921717,
    "updatedAt":1434091515411,
    "shortDomain":"tn.gg",
    "defaultRedirectUrl":"https://museum.com/displayWorks/catalogue.php?catalogue_id=UVpfh4EFsBpasUmnVDWdktKs",
    "redirectUrl":"https://museum.com/displayWorks/catalogue.php?catalogue_id=UVpfh4EFsBpasUmnVDWdktKs",
    "type":"thng",
    "evrythngUrl":"https://api.evrythng.com/thngs/UVpfh4EFsBpasUmnVDWdktKs",
    "shortId":"a3gZQXfF",
    "evrythngId":"UVpfh4EFsBpasUmnVDWdktKs",
    "hits":0
  }
]

Generate a QR Code

Once a short URL has been created in the Platform, you can easily generate a customizable QR code that contains the short URL, which can then be attached to the physical object. The QR code can be scanned using any standard bar code / QR code scanning application, which will point to the redirector and will be dynamically redirected to the target application.

GET https://tn.gg/:shortId.qr
Accept: image/:format

curl -H "Accept: image/png" \
  -X GET 'https://tn.gg/EESmUazB.qr' \
  -o output.png

Output Type

The accept header is used to choose the :format (the file format as a MIME type) of the generated QR code. Available formats:

  • image/png (default, PNG bitmap image)
  • image/svg+xml (SVG vector)
  • application/pdf (vector PDF document)

You can also use alias endpoints to generate QR code in the preferred format:

PNG

GET https://tn.gg/:shortId.png

SVG

GET https://tn.gg/:shortId.svg

PDF

GET https://tn.gg/:shortId.pdf

Generations Options

The following query parameter options are available for QR code generation:

  • h - The image height in pixels, from 95 to 800.
  • w - The image width in pixels, from 95 to 800.
  • tpl - The template for the QR code layout. Can be either default or default-shortid (including the short ID).
  • ecl - The error correction level required. Must be one of L, M, Q, or H in ascending order of the amount of data redundancy added.

Because the short URL is fixed (23 characters, from which 10 are used for the shortId), the QR code generated is version 2 (25x25 modules) using the error correction level Q (25% of error correction capacity).

An example QR code generation request is shown below for a large QR code with a high level of error correction applied:

https://tn.gg/EESmUazB.png?w=256&h=256&ecl=H&tpl=default