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

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

Data Description Example
title Website Title Google
description Description Summary Search webpages, images, videos and more.
image Preview Image https://www.google.com/images/logo.png
url Destination URL https://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 Code Description
400 Generic error
401 Cannot verify API access key
403 Invalid or blank API access key
423 Forbidden by robots.txt
424 Invalid response status code
429 Too 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