Redirections

Redirections allow physical 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)
https://api.evrythng.io/v2/redirections (see below for usage of this endpoint)

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?evrythngId=:thngID
Authorization: $OPERATOR_API_KEY
Accept: application/json

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

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
}

📘
Aliased endpoint
There is an aliased version of this endpoint available at /v2/redirections
This version of the endpoint allows you to fetch redirections for a shortUrl by appending the ?domain={domain} query string parameter, for example:
https://api.evrythng.io/v2/redirections?evrythingId=U6M2D8DUm9mdnPwaRnecXkah&domain=tn.gg

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

Redirections

📘
Redirector

RedirectionDocument Data Model

Create a Redirection

📘
Thng and Product Redirections

🚧
Note

Read a Redirection

📘
Note

📘
Aliased endpoint

Update a Redirection

Delete a Redirection

Read all Redirections on a Thng

Generate a QR Code

Output Type

Generations Options

📘Redirector

RedirectionDocument Data Model

Create a Redirection

📘Thng and Product Redirections

🚧Note

Read a Redirection

📘Note

📘Aliased endpoint

Update a Redirection

Delete a Redirection

Read all Redirections on a Thng

Generate a QR Code

Output Type

Generations Options

📘
Redirector

📘
Thng and Product Redirections

🚧
Note

📘
Note

📘
Aliased endpoint