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:

EndpointGETPOST
http://api.linkpreview.netYesYes
https://api.linkpreview.netYesYes

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 (&).

NameDescriptionExampleRequired
keyYour API Key123456Yes
qURL to inspect*https://www.google.comYes

*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.


Response

Successful API response will be sent with HTTP status code 200 and it will contain application/json data.

DataDescriptionExample
titleWebsite TitleGoogle
descriptionDescription SummarySearch webpages, images, videos and more.
imagePreview Imagehttps://www.google.com/images/logo.png
urlDestination URLhttps://www.google.com

*You should always validate/sanitize API response before using it.


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 Status CodeDescription
400Generic error
401Cannot verify API access key
403Invalid or blank API access key
423Forbidden by robots.txt
425Invalid response status code (actual response code from the remote server)
426Too many requests per second on a single domain
429Too many requests / rate limit exceeded

Example Response (HTTP Status code 401):

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

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) {
        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