Quick Start

API Request (GET):

http://api.linkpreview.net/?key=123456&q=https://www.google.com

API Response (JSON):

{
   "title":"Google",
   "description":"Search webpages, images, videos and more.",
   "image":"https://www.google.com/images/logo.png",
   "url":"https://www.google.com"
}

Requests can be made using POST method as well. In the following example we are using curl command line utility to submit query parameters in the body of the request.

API Request (POST):

curl --data "key=123456&q=https://www.google.com" https://api.linkpreview.net

API Endpoints

We provide both HTTP and HTTPS endpoints for our service:

Endpoint GET POST
http://api.linkpreview.net Yes Yes
https://api.linkpreview.net Yes Yes

Parameters

Our API uses query parameters since they are the simplest and the most common type of parameters. When using GET request they appear at the end of the request URL after a question mark (?), with name=value pairs separated by ampersands (&).

Name Description Example Required
key Your API Key 123456 Yes
q URL to inspect* https://www.google.com Yes
fields Comma-separated list of fields to return image_x, icon_type, locale No

*Since this parameter can contain reserved characters :/?#[]@!$&'()*+,;= it should be sent as percent-encoded (encodeURIComponent/urlencode).

API Keys

LinkPreview uses API keys for authorization. An API key is a special access token that the client needs to provide as a query parameter when making API calls. You can generate and revoke your access keys here. For maximum security always use HTTPS and POST Requests.

Default and Additional Fields

LinkPreview can return additional fields based on your current subscription plan. Example request - asking for three additional fields:

http://api.linkpreview.net/?key=123456&fields=image_x,icon_type,locale&q=https://www.google.com

Fields specification:

Name Type Description Example response Subscription Plan
title string Website title. Returned by default. Google Available on all plans
description string Description summary. Returned by default. Search webpages, images, videos and more. Available on all plans
image string Preview image URL. Returned by default. https://www.google.com/images/logo.png Available on all plans
url string Destination URL. Returned by default. https://www.google.com Available on all plans
canonical string Canonical or "preferred" version of a web page. Defaults to blank "" if not found. https://www.google.com/en Basic, Pro, Enterprise
locale string Web page's locale formatted as language_TERRITORY. Defaults to "en_US" if not found. You can use this to detect RTL languages or to display other language-specific elements. en_GB Basic, Pro, Enterprise
site_name string Short domain name formatted as top_level_domain+1. Use this to display short name instead of a full link. google.com Basic, Pro, Enterprise
image_x number Image width in pixels. See image processing. 600 Pro, Enterprise
image_y number Image height in pixels. See image processing. 400 Pro, Enterprise
image_size number Image size in bytes. See image processing. 643252 Pro, Enterprise
image_type string Image MIME content type. image/jpeg Pro, Enterprise
icon string Website icon URL, also known as favicon. https://www.google.com/favicon.ico Pro, Enterprise
icon_x number Website icon width in pixels. 50 Pro, Enterprise
icon_y number Website icon height in pixels. 50 Pro, Enterprise
icon_size number Website icon size in bytes. 48322 Pro, Enterprise
icon_type string Website icon MIME content type. image/x-icon Pro, Enterprise
image_key string Image S3 key. Used to generate URL to the image at Amazon S3 bucket. cdn/37814cb53005b72397c6646b340d71 Self-Hosted only
icon_key string Website icon S3 key. Used to generate URL to the image at Amazon S3 bucket. cdn/26c28ec312391a13003a33b0013393 Self-Hosted only

Response

Successful API response will be sent with HTTP status code 200 and it will contain application/json data. You should always validate/sanitize API response before using it.

Default Response:

{
   "title":"Google",
   "description":"Search webpages, images, videos and more.",
   "image":"https://www.google.com/images/logo.png",
   "url":"https://www.google.com"
}

Extended Response:

{
   "title":"Google",
   "description":"Search webpages, images, videos and more.",
   "image":"https://www.google.com/images/logo.png",
   "url":"https://www.google.com"
   "image_size": 896933,
   "image_type: "image/gif",
   "image_x: 1100,
   "image_y: 440,
   "icon": "https://www.google.com/favicon.ico",
   "icon_type": "image/x-icon",
   "icon_x": 32,
   "icon_y": 32,
   "locale: "en_US"
}

Errors

If a request cannot be completed successfully, the response from the API will contain HTTP status code 400 or higher. The response from the API may also contain one or more error elements in the response. This information can be used to determine what went wrong. Each of these elements may contain an error code, message, and (if applicable) other informative values to assist in debugging the problem.

Error Code Description
400 Generic error
401 Cannot verify API access key
403 Invalid or blank API access key
423 Forbidden by robots.txt - the requested website does not allow us to access this page
425 Invalid response status code (with the actual response code we got from the remote server)
426 Too many requests per second on a single domain
429 Too many requests / rate limit exceeded

Example Error Response (HTTP Status code 401):

{
   "title":"",
   "description":"Linkpreview service denied",
   "image":"",
   "url":"",
   "error":401
}
      

Image Processing and Validation

Sometimes the website can provide og:image that is not accessible, served via the insecure HTTP protocol, invalid, or the URL simply wrong. LinkPreview API can help and process images to validate them and extract additional data such as image width, image height, content-type, and size. Supported web image formats include jpeg, png, gif, ico, and webp images up to 5MB in size.

To validate the image, send your request with additional field image_size and check if the returned image size is greater than zero. You can also use image width and height parameters to calculate the image orientation (portrait/landscape) and use that to decide which of your layouts to render. You can use image size to discard images that are too small or too big for your specific layout.

Our self-hosted plan includes an extra feature to store all processed images to your Amazon S3 bucket. This way you can create CDN and safely serve all images directly from your Amazon S3 bucket using HTTPS. Please contact us for more info.

Same-origin policy

Bypassing same-origin policy is handled automatically. You can use either CORS or JSONP requests to bypass same-origin policy in your front-end application. Since CORS allows you to use POST requests we recommend this method for all modern applications. JSONP is provided for compatibility reasons.

Caching

LinkPreview robot will cache requested pages and it will check for changes only once in a while, so any updates will get noted on its next crawl and not immediately. The exact TTL depends on various parameters and it can take up to a day for cache to expire.

Examples

Shell / cURL:

curl --data "key=123456&q=https://www.google.com" https://api.linkpreview.net

jQuery simple CORS request:

$.ajax({
    url: "https://api.linkpreview.net?key=123456&q=https://www.google.com",
    success: function(result){
        console.log(result);
    }
});

jQuery preflight CORS request:

$.ajax({
    url: "https://api.linkpreview.net?key=123456&q=https://www.google.com",
    type: "GET",
    contentType: "application/json",
    success: function(result){
        console.log(result);
    }
});
        

jQuery cross-origin request using JSONP:

var target = "https://www.google.com";
var key    = "123456";

$.ajax({
    url: "https://api.linkpreview.net",
    dataType: "jsonp",
    data: {q: target, key: key},
    success: function (response) {
        if (response.error) {
            console.log(response.description);
            return;
        }
        console.log(response);
    }
});
        

POST request using javascript / Fetch API

var data = {key: '123456', q: 'https://www.google.com'}

fetch('https://api.linkpreview.net', {
  method: 'POST',
  mode: 'cors',
  body: JSON.stringify(data),
})
  .then(res => res.json())
  .then(response => console.log(response))

POST request using javascript / axios

import axios from 'axios'

axios.post(
  'https://api.linkpreview.net',
  {
    q: 'https://www.google.com',
    key: '123456'
  }).then(resp => {
  console.log(resp.data)
})

PHP using simple file_get_contents:

$target = urlencode("https://www.google.com");
$key = "123456";

$ret = file_get_contents("https://api.linkpreview.net?key={$key}&q={$target}");
print_r(json_decode($ret));
        

POST request using Python

import requests

url = 'https://api.linkpreview.net?key=123456&q=https://www.google.com'
response = requests.request("POST", url)
print(response.text)
        

POST request using Ruby

require('httparty')

response = HTTParty.post('https://api.linkpreview.net?key=123456&q=https://www.google.com')
puts response.body
        

Frontend example using Bulma CSS and Javascript / Fetch API

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.1/css/bulma.min.css">
  </head>
  <body>
  <section class="section">
    <div class="container">
      <div class="box" style="width:300px">
        <img id="myimage" src="">
        <div class="is-clipped">
          <div id="mytitle" class="has-text-weight-bold"></div>
          <div id="mydescription" class="mt-2"></div>
          <div id="myurl" class="mt-2 is-size-7"></div>
        </div>
      </div>
    </div>
  </section>

  <script>
    var data = {key: '123456', q: 'https://www.google.com'}

    fetch('https://api.linkpreview.net', {
      method: 'POST',
      mode: 'cors',
      body: JSON.stringify(data),
    })
      .then(res => res.json())
      .then(response => {
    document.getElementById("mytitle").innerHTML = response.title
    document.getElementById("mydescription").innerHTML = response.description
    document.getElementById("myimage").src = response.image
    document.getElementById("myurl").innerHTML = response.url
    })
  </script>
  </body>
</html>
        

Codepen