Preview

The primary endpoint of Peekalink. Given a link, it will return a preview for it.

  • Method: POST
  • Accepts: JSON
  • Returns: JSON

Endpoint

https://api.peekalink.io/

Sample code

import requests

response = requests.post(
    "https://api.peekalink.io/",
    headers={"X-API-Key": "YourSecretKey"},
    data={"link": "https://bit.ly/3frD2OP"},
)

Sample response

{
  "url": "https://bit.ly/3frD2OP",
  "domain": "bit.ly",
  "lastUpdated": "2020-11-23T16:55:51.648662Z",
  "nextUpdate": "2020-11-24T16:55:51.615769Z",
  "contentType": "html",
  "mimeType": "text/html",
  "redirected": true,
  "redirectionUrl": "https://www.youtube.com/watch?feature=youtu.be&v=dQw4w9WgXcQ",
  "redirectionCount": 2,
  "redirectionTrail": [
    "https://youtu.be/dQw4w9WgXcQ",
    "https://www.youtube.com/watch?feature=youtu.be&v=dQw4w9WgXcQ"
  ],
  "title": "Rick Astley - Never Gonna Give You Up (Video)",
  "description": "Rick Astley's official music video for “Never Gonna Give You Up” \nListen to Rick Astley: https://RickAstley.lnk.to/_listenYD\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/subscribeYD\n\nFollow Rick Astley:\nFacebook: ht..",
  "name": "RickAstleyVEVO in YouTube",
  "trackersDetected": true,
  "icon": {
    "url": "https://cdn.peekalink.io/public/images/e54bc7cf-047a-413a-b707-14626e9094e0/19f0e08e-d03b-4edf-9bf1-9c2ea72b7536.jpg",
    "width": 144,
    "height": 144
  },
  "image": {
    "url": "https://cdn.peekalink.io/public/images/7b4c43dd-05ee-47b7-937f-a4b65c9bf7ea/44a88bb2-8990-4530-836a-4c746f00e4e9.jpe",
    "width": 640,
    "height": 480
  },
  "details": {
    "type": "youtube",
    "videoId": "dQw4w9WgXcQ",
    "duration": "213.0",
    "viewCount": 787905032,
    "likeCount": 7200677,
    "dislikeCount": 228169,
    "commentCount": 1162359,
    "publishedAt": "2009-10-25T06:57:33Z"
  }
}

Response variations

In general, regardless of whatever link you preview, we will try to deliver the same response attributes, however there are some exceptions bound to happen.

image or icon missing

This will happend when you are previewing a link with contentType: "html" and we could not find any icon nor image to preview.

title or description missing

This will happen when you are previewing a link with contentType: "image" | "video" | "gif".

Media items do not provide these details, so they will be missing in the response.

details missing or different

Details is the special attribute where we attach extra information about the link you are previewing through custom integrations with services such as YouTube, Twitter and GIPHY.

When you preview a Twitter link, this object will contain attributes like likesCount, when previewing a YouTube link, it will contain attributes like duration.

You can read more about the details attribute here.

Response attributes

url

The url of the link previewed.

Type

string

Example

{
  // ...
  "url": "https://bit.ly/3frD2OP"
  // ...
}

We automatically try all urls for HTTPs availability. If it is available, we will upgrade your link. e.g. http://somedomain.com -> https://somedomain.com

If you'd like to benefit from this, make sure that your users always get sent to response.url and not your original link preview url.

domain

The domain of the link previewed.

Type

string

Example

{
  // ...
  "domain": "bit.ly"
  // ...
}

lastUpdated

The date when the link preview was last updated.

Type

string

Example

{
  // ...
  "lastUpdated": "2020-11-23T16:55:51.648662Z"
  // ...
}

nextUpdate

The date when the link preview will be updated again.

This is calculated based on HTTPs caching and invalidation mechanisms.

Type

string

Example

{
  // ...
  "nextUpdate": "2020-11-23T16:55:51.648662Z"
  // ...
}

contentType

The type of the content that the link points to.

Type

string

Possible values

  • html
  • image
  • video
  • gif

Example

{
  // ...
  "nextUpdate": "2020-11-23T16:55:51.648662Z"
  // ...
}

mimeType

The official mime type type of content the link points to.

Type

string

Possible values

Please see the whole list here.

Example

{
  // ...
  "mimeType": "text/html"
  // ...
}

redirected

Whether the previewed link contained redirects.

Type

boolean

Example

{
  // ...
  "redirected": "true"
  // ...
}

redirectionUrl

If the link contained a redirection (redirected: true), this will be the final redirection url.

Type

string|null

Example

{
  // ...
  "redirectionUrl": "https://www.youtube.com/watch?feature=youtu.be&v=dQw4w9WgXcQ"
  // ...
}

redirectionTrail

If the link contained a redirection (redirected: true), this will contain the list of all the urls it was redirected from.

Type

Array<string>|null

Example

{
  // ...
  "redirectionTrail": [
    "https://youtu.be/dQw4w9WgXcQ",
    "https://www.youtube.com/watch?feature=youtu.be&v=dQw4w9WgXcQ"
  ]
  // ...
}

title

If the link contentType was html, it will contain its title.

Type

string|null

Example

{
  // ...
  "title": "Rick Astley - Never Gonna Give You Up (Video)"
  // ...
}

description

If the link contentType was html, it will contain its description.

Type

string|null

Example

{
  // ...
  "description": "Rick Astley's official music video for “Never Gonna Give You Up” \nListen to Rick Astley: https://RickAstley.lnk.to/_listenYD\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/subscribeYD\n\nFollow Rick Astley:\nFacebook: ht.."
  // ...
}

name

The name of the owner of the link. If contentType: "html" this will be the domain of the link in uppercase.

Custom integrations

Youtube

when previewing Youtube video links, this will be the name of the Youtube channel that uploaded the video, e.g.PewDiePie.

Twitter

When previewing Twitter tweets, this will be the handle of the Twitter user that created the tweet, e.g. @IAmDevloper.

Type

string|null

Example

{
  // ...
  "description": "Rick Astley's official music video for “Never Gonna Give You Up” \nListen to Rick Astley: https://RickAstley.lnk.to/_listenYD\n\nSubscribe to the official Rick Astley YouTube channel: https://RickAstley.lnk.to/subscribeYD\n\nFollow Rick Astley:\nFacebook: ht.."
  // ...
}

trackersDetected

Wether trackers were detected on the previewed link which would compromise your users privacy if clicked upon.

Type

boolean

Example

{
  // ...
  "trackersDetected": true
  // ...
}

icon

The icon for the previewed link.

Will be null when no icon was found or contentType is not html.

Type

string | null

Example

{
  // ...
  "icon": {
    "url": "https://cdn.peekalink.io/public/images/e54bc7cf-047a-413a-b707-14626e9094e0/19f0e08e-d03b-4edf-9bf1-9c2ea72b7536.jpg",
    "width": 144,
    "height": 144
  }
  // ...
}

image

The image for the previewed link.

Will be null when no suitable image was found but worry not, we put in a lot of work to guarantee that this attribute is some 90% of the time available for all content types (image, gif, video, html)

Type

string | null

Example

{
  // ...
  "image": {
    "url": "https://cdn.peekalink.io/public/images/7b4c43dd-05ee-47b7-937f-a4b65c9bf7ea/44a88bb2-8990-4530-836a-4c746f00e4e9.jpe",
    "width": 640,
    "height": 480
  }
  // ...
}

details

Extra details related to the previewed link generated by to our custom platform integrations.

It should be differentiated with its type attribute.

Possible type values are

  • youtube
  • twitter

Type

Object | null

Examples

Previewing a Youtube video link with url https://youtu.be/dQw4w9WgXcQ

{
  // ...
  "details": {
    "type": "youtube",
    "videoId": "dQw4w9WgXcQ",
    "duration": "213.0",
    "viewCount": 787905032,
    "likeCount": 7200677,
    "dislikeCount": 228169,
    "commentCount": 1162359,
    "publishedAt": "2009-10-25T06:57:33Z"
  }
  // ...
}

Previewing a Twitter tweet link with url https://twitter.com/DalaiLama/status/1300002847107379200

{
  // ...
  "details": {
    "type": "twitter",
    "statusId": "1300002847107379200",
    "retweetCount": 2397,
    "likesCount": 11734,
    "publishedAt": "2020-08-30T09:30:06Z"
  }
  // ...
}
Setup Is available