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

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.

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