Welcome to microlink API!
You can use it to retrieve relevant information from any link. The service is oriented to build embed previsualizations of third-party links in your project.
From the url provided as input, we can detect the following information:
  • author — eg. SpaceX
    A human-readable representation of the author's name.
  • date — eg. 2018-01-24T18:39:47.000Z
    An ISO 8601 representation of the date the article was published.
  • description — eg. First static fire test of Falcon Heavy…
    The publisher's chosen description of the article.
  • image — eg. https://cdninstagram.com/…/26867070_171196260320789.jpg
    An image URL that best represents the article.
  • video — eg. https://cdninstagram.com/…/26867070_171196260320789.mp4
    A video URL that best represents the article.
  • lang — eg. en
    An ISO 639-1 representation of the url content language.
  • logo — eg. https://www.instagram.com/static/images/ico/favicon-192.png/b407fa101800.png
    An image URL that best represents the publisher brand.
  • publisher — eg. Instagram
    A human-readable representation of the publisher's name.
  • title — eg. SpaceX on Instagram
    The publisher's chosen title of the article.
  • url — eg. https://www.instagram.com/p/BeV6tOhFUor
    The URL of the article.
Complementing the information obtained, we provide you a set of extra features that enrich your links previsualizations and improve your engagement:
  • Take a screenshot of the website (partial or full page).
  • Get a predominant color palette per each image detected.
  • Make easy embed content directly in your HTML markup.
  • Prerendering mode, useful for getting more information from websites that use client-side frameworks.
  • Export to PDF (soon, ping us if you are interested!)
Entering an URL, you will receive the information behind the link.
curl https://api.microlink.io?url=https://instagram.com/p/BeV6tOhFUor
The above API request generate the following response:
{
  "status": "success",
  "data": {
    "image": {
      "url": "https://scontent-iad3-1.cdninstagram.com/vp/5c28a1b9f5ad679ab27f3af6f1becf80/5B831279/t51.2885-15/fr/e15/s1080x1080/26867070_171196260320789_7698587573655961600_n.jpg",
      "width": 1080,
      "height": 607,
      "type": "jpg",
      "size": 45156,
      "size_pretty": "45.2 kB"
    },
    "video": {
      "url": "https://scontent-iad3-1.cdninstagram.com/vp/2e193a12d863ef5b3498931e85d5af3c/5B832A52/t50.2886-16/26680591_1497085977080751_971884209264132096_n.mp4",
      "width": 640,
      "height": 360,
      "type": "mp4",
      "size": 1056046,
      "size_pretty": "1.06 MB",
      "duration": 21.633333,
      "duration_pretty": "22s"
    },
    "author": "SpaceX",
    "publisher": "Instagram",
    "title": "SpaceX on Instagram: “First static fire test of Falcon Heavy complete—one step closer to first test flight!”",
    "date": "2018-01-24T18:39:47.000Z",
    "lang": "en",
    "description": "170.4k Likes, 2,837 Comments - SpaceX (@spacex) on Instagram: “First static fire test of Falcon Heavy complete—one step closer to first test flight!”",
    "logo": {
      "url": "https://www.instagram.com/static/images/ico/favicon-192.png/68d99ba29cc8.png",
      "width": 192,
      "height": 192,
      "type": "png",
      "size": 50,
      "size_pretty": "33.9 kB"
    },
    "url": "https://www.instagram.com/p/BeV6tOhFUor"
  }
}
The API is shipped as a microservice exposed as an HTTP service over SSL.
For the Free plan, the endpoint is https://api.microlink.io
Under a Professional plan, the endpoint is https://pro.microlink.io.
Just call / with method GET. Nothing else.
The API Parameters need to be provided as query parameters in the request.
curl https://api.microlink.io?url=https://www.instagram.com/p/BeV6tOhFUor&userAgent=myBrowser
It does not matter if you use a camel or snake case, both are supported
curl https://api.microlink.io?url=https://www.instagram.com/p/BeV6tOhFUor&user_agent=myBrowser
We apply different API quota based pricing plans.
Unauthenticated requests use Free plans. It doesn't need to do nothing additional.
Under a Professional plans, you need to authenticate your requests.
It should be done providing the header x-api-key with your API Key as value in all your requests.
If you have any trouble, please contact us.
The authentication will be done adding your API Key as value of the x-api-key header on your requests:
curl -H "x-api-key: MyApiToken" https://pro.microlink.io?url=http://a.co/cWDWLda -i | grep -i "x-pricing-plan"
You can check the pricing plan associated with the request with x-pricing-plan header on the response:
x-pricing-plan: pro
For the Free plan, we allow a maximum of 250 requests every 24 hours and one request per second.
We limit the number of calls you can make over a certain period of time. Rate limits vary and are specified by the following header in all responses:
HeaderDescription
X-Rate-Limit-LimitThe maximum number of requests that the consumer is permitted to make per minute.
X-Rate-Limit-RemainingThe number of requests remaining in the current rate limit window.
X-Rate-Limit-ResetThe time at which the current rate limit window resets in UTC epoch seconds.
Under the Professional plan, rate limits start from 1,000 requests every 24 hours with unlimited concurrency.
When the rate limit is exceeded an error is returned with the status 429 Too Many Requests.
When you exceeded your daily quota, you need to wait until quota reset or increment your plan. See pricing for more information.
If you already have a Professional plan but you need to increment your daily quota, contact us.
You can check your rate limit quota with x-rate header on the response:
curl https://api.microlink.io?url=http://a.co/cWDWLda -i | grep -i "x-rate"
It should be looks like:
x-rate-limit-reset: 1530172275
x-rate-limit-remaining: 249
x-rate-limit-limit: 250
All the responses are served as JSON – unless you use the embedded support.
Our response format is based on JSend specification.
This means that every API call generates a response with status, data and message fields.

status

required
type: string
The status associated with the response. The value can be:
StatusDescription
successThe request was resolved successfully. Associated with 2xx HTTP status code.
failThe request failed. Probably a missing or wrong value for a parameter. Associated with 4xx HTTP status code.
errorUh oh. Something unexpected happened. Associated with 5xx HTTP status code.
A simple rule here is, if the request was resolved successfully, then the success status will be associated. In other case check for fail or error.

data

type: object
Your API response payload. Here you can find all the information related with the link provided, like description, title, image, etc.

message

type: string
An additional field to attach extra information, such as an error message or explanation.
In order to use the lowest bandwidth capacity possible, microlink supports brotli and gzip compression.
Compression could reduce the payload size up to 70%, so we strongly recommend always use it.
If you are performing the API request using a web browser or our SDK, compression will be enabled by default.
Otherwise, ensure to specify it using Accept-Encoding header.
As part of the negotiation process you need to specify accept-encoding header for indicate what encoding you want to use:
curl -H "accept-encoding: br,gzip" -I -X GET https://api.microlink.io/?url=https://www.reddit.com | grep -i "content-encoding"
Check the content-encoding header in the response for determinate what encoding was used:
Content-Encoding: br
We follow a response cache policy for avoiding generate the same response twice in a period of time.
We algorithm for caching response is quite simple:
  • First time you query for a resource that not was previously served, we will create it, what is known as cache MISS.
  • The successive requests for the resource will consume the cached version of the resource, what is known as cache HIT.
The cache status is reflected using the response header x-cache-status.
The period of time the resource is cached is known as Time To Live (TTL).
The TTL is dynamically adjusted per each domain, being 1 hour the minimum and 5 days the maximum value allowed.
You can see the TTL value in a human friendly way as x-cache-expired-at in the reponse headers.
It's reflected as cache-control as well to tell browsers how much time they can serve the same resource until cache expiration.
Sometimes you need to invalidate cache hits intentionally. For do that, use force paramter for regenerating the cache.
The first time an uncached resource is queried, the API will extract the information from the link:
curl -i https://api.microlink.io/?url=https://www.reddit.com | grep -i "x-cache-status"
You can check that from x-cache-status headers of the response. First time, the value will be MISS:
x-cache-status: MISS
Now if you query again for the same resource, a cached version will be served based on the first request, and x-cache-status value will be HIT:
x-cache-status: HIT
You can know how much time the resource will cache checking x-cache-expired-at header:
x-cache-expired-at: 3d 29m 6.9s
required
type: string
The URL for getting information based on the content.
It should be reachable and accessible by the service.
The URL protocol matters: If the target URL have relative URLs inside (e.g. images or videos), then the URL provided will be used to resolved relatives URLs into absolute.
This means that if you provide an HTTPS, then all relatives URLs will be resolved under SSL.
At least, you need to provide an URL to usage the service.
curl https://api.microlink.io/?url=https://theverge.com
type: boolean|string
default 'auto'
Prerendering is a process to preload all elements on the page in preparation for a web crawler to see it.
The action is performed using a headless browser for entering in the target URL, wait until DOM events are done and getting the HTML generated by the client-side application.
This is necessary for whatever client-side application that builds the DOM at the moment the user enters in the site, like React, Ember, Angular, etc.
Ideally, you don't need to think about prerendering. We automagically determinate if the target URL needs or not prerendering
This is reflected using the auto value. On the other hand, you can pass a boolean to enable or disable it explicitly.
If the prerendering technique fails or timeout after 8 seconds of waiting, it will be fallback on the normal mode.
In order to determinate how the content was obtained, you can check x-fetch-time and x-fetch-mode from the response headers
curl -i https://api.microlink.io/?url=https://www.sportsnet.ca/hockey/nhl/leafs-john-tavares-return-new-york-hope-positive | grep -i "x-fetch"
It should be looks like:
x-fetch-mode: prerender
x-fetch-time: 5002.364ms
type: boolean|string
default false
Take a screenshot of the website. The image will be hosted at imgur.com.

Device emulation

The API supports take screenshots using different viewport configuration.
In order to setup the viewport settings, we provide device that it's a list of device presets viewports you can use.
To use it just provide one of the supported device names:
device descriptorwidthheightscalemobile?touch?landscape?
blackberry z303606402truetruefalse
blackberry z30 landscape6403602truetruetrue
blackberry playbook60010241truetruefalse
blackberry playbook landscape10246001truetruetrue
galaxy note 33606403truetruefalse
galaxy note 3 landscape6403603truetruetrue
galaxy note ii3606402truetruefalse
galaxy note ii landscape6403602truetruetrue
galaxy s iii3606402truetruefalse
galaxy s iii landscape6403602truetruetrue
galaxy s53606403truetruefalse
galaxy s5 landscape6403603truetruetrue
kindle fire hdx80012802truetruefalse
kindle fire hdx landscape12808002truetruetrue
lg optimus l703846401.25truetruefalse
lg optimus l70 landscape6403841.25truetruetrue
macbook pro 1312808001falsefalsefalse
macbook pro 1514409001falsefalsefalse
microsoft lumia 5506403602truetruefalse
microsoft lumia 9503606404truetruefalse
microsoft lumia 950 landscape6403604truetruetrue
nexus 1080012802truetruefalse
nexus 10 landscape12808002truetruetrue
nexus 43846402truetruefalse
nexus 4 landscape6403842truetruetrue
nexus 53606403truetruefalse
nexus 5 landscape6403603truetruetrue
nexus 5x4127322.625truetruefalse
nexus 5x landscape7324122.625truetruetrue
nexus 64127323.5truetruefalse
nexus 6 landscape7324123.5truetruetrue
nexus 6p4127323.5truetruefalse
nexus 6p landscape7324123.5truetruetrue
nexus 76009602truetruefalse
nexus 7 landscape9606002truetruetrue
nokia lumia 5203205331.5truetruefalse
nokia lumia 520 landscape5333201.5truetruetrue
nokia n94808541truetruefalse
nokia n9 landscape8544801truetruetrue
imac 21.5198010801falsefalsefalse
imac 27256014401falsefalsefalse
ipad76810242truetruefalse
ipad mini76810242truetruefalse
ipad mini landscape10247682truetruetrue
ipad pro102413662truetruefalse
ipad pro landscape136610242truetruetrue
ipad landscape10247682truetruetrue
iphone 43204802truetruefalse
iphone 4 landscape4803202truetruetrue
iphone 53205682truetruefalse
iphone 5 landscape5683202truetruetrue
iphone 63756672truetruefalse
iphone 6 plus4147363truetruefalse
iphone 6 plus landscape7364143truetruetrue
iphone 6 landscape6673752truetruetrue
iphone x3758123truetruefalse
iphone x landscape8123753truetruetrue

Specific parameters

Although device is a list of popular device presets, you can setup viewports settings manually:
ParameterDescription
device_scale_factornumberSpecify device scale factor (defaults to 1).
full_pagebooleanWhen true, takes a screenshot of the full scrollable page (defaults to false).
has_touchboolean or stringSpecifies if viewport supports touch events (defaults to false).
heightnumber Page height in pixels.
is_landscapeboolean Specifies if viewport is in landscape mode (defaults to false).
is_mobileboolean Whether the meta viewport tag is taken into account (defaults to false).
omit_backgroundboolean Hides default white background and allows capturing screenshots with transparency (defaults to true).
qualitynumber The quality of the image, between 0 to 100. Not applicable to 'png' images.
typestring Specify screenshot type, could be either 'jpeg' or 'png' (defaults to 'png').
widthnumber Page width in pixels.
When you take a screenshot snapshot such as
curl https://api.microlink.io/?url=https://microlink.io&screenshot&filter=screenshot
The image will be hosted at imgur.com as png by default.
{
  "status": "success",
  "data": {
    "screenshot": {
      "url": "https://i.imgur.com/fcZxSQe.png",
      "width": 1280,
      "height": 800,
      "type": "png",
      "size": 185818,
      "size_pretty": "186 kB"
    }
  }
}
Providing a device name supported as value for screenshot, we will take the screenshot using the specific device settings (viewport, width, height, etc).
<img
  style="max-width: 250px"
  src="https://api.microlink.io/?url=https://microlink.io&screenshot=iphone%206&embed=screenshot.url"
/>
type: boolean
default false
Enabling it will return you more information related with color schema of the images detected:
FieldDescription
palettearrayA collection of hexadecimal colors from most dominant color to least.
background_colorstringThe best color with good WCAG contrast ratio that can be used as background color representation of the image.
colorstringThe best color overlayed over background_color.
alternative_colorstringIt will be the second best color. If there are only two colors parsed, it will default to color.
The palette API Parameter makes possible get contextual information about your images in terms of color composition:
curl https://api.microlink.io/?url=https://news.ycombinator.com&palette&filter=image
{
  "status": "success",
  "data": {
    "image": {
      "url": "https://news.ycombinator.com/y18.gif",
      "width": 18,
      "height": 18,
      "type": "gif",
      "size": 100,
      "size_pretty": "100 B",
      "palette": [
        "#fc6404",
        "#fca46c",
        "#833301"
      ],
      "background_color": "#FCA46C",
      "color": "#712D01",
      "alternative_color": "#813201"
    }
  }
}
type: string
A comma-separated list of property paths to pick from response payload.
It supports nested path as well using dot notation.
This parameter has been designed to make API payload tiny as possible, improving response bandwidth timing.
It's a good practice to filter just the values that you're going to consume:
curl https://api.microlink.io/?url=https://news.ycombinator.com&filter=url,title
{
  "status": "success",
  "data": {
    "url": "https://news.ycombinator.com/",
    "title": "Hacker News"
  }
}
type: string
The embed parameter is for embedding a field directly in your HTML markup, using the properly encoding (text, images, etc).
You can use dot notation to reference a nested data field of the payload.
For example, if you want to embed an image just provide embed=image.src and the image will be rendered.
You can call the API directly from a html tag:
<img
  src="https://api.microlink.io?url=https://news.ycombinator.com&embed=logo"
/>
It will render the hacker news logo:
type: boolean
default false
It enables audio source detection from the target URL.
In that case, the audio source URL detected will be a browser friendly format.
The audio content also provides you contextual information like format size or duration
curl https://api.microlink.io/?url=https://soundcloud.com/theaipodcast/gtc-weather&audio&filter=video
Also, we provide a pretty version of these values as part of the reponse. They are human friendly
{
  "status": "success",
  "data": {
    "video": {
      "url": "https://scontent-iad3-1.cdninstagram.com/vp/18761abb46172be3e769ff635fdbec2c/5B979992/t50.2886-16/26680591_1497085977080751_971884209264132096_n.mp4",
      "width": 640,
      "height": 360,
      "type": "mp4",
      "size": 1056046,
      "size_pretty": "1.06 MB",
      "duration": 21.633333,
      "duration_pretty": "22s"
    }
  }
}
type: boolean
default false
It enables video source detection from the target URL.
In that case, the video source URL detected will be a browser friendly format.
Extending the video content is useful specially when you are working with visual content, like link previews
curl https://api.microlink.io/?url=https://instagram.com/p/BeV6tOhFUor&video&filter=video
Like audio, we provide contextual informationa about the video detected, such as a pretty version of these value that they are human friendly
{
  "status": "success",
  "data": {
    "audio": {
      "url": "https://cf-media.sndcdn.com/clcG6IDMnbiy.128.mp3?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiKjovL2NmLW1lZGlhLnNuZGNkbi5jb20vY2xjRzZJRE1uYml5LjEyOC5tcDMiLCJDb25kaXRpb24iOnsiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE1Mzc3Mjg4MjJ9fX1dfQ__&Signature=RLWbZ48H9pbqZtUz9Wu3J95uPU2SUwUUuuOq3OEDOvIeGiQlvn71gody91i~Tp0zKPfM66zfnG1Zpw4RT34poCIzPTIWi~B7Gga6x1IvvVksKSRA0u~Jdx2YZv14OAzeeJn1cOIibv8MeS3Owa5y0rHUkL2EI2xVMRNezWf4yQM3~gam5yoB4HtXBE7Axsd2McFxXps6KFtX~JlULMd7H3JMCVlWSGrP-dfzBH~DR6O-6jzwmBEGkdYHCf17nqwNYfo8c6ROZdBvbCykXaaZcA1z46LvXnZr18EihvQrgd7OE6CYYOKg1VOA2rl4h16MdqICQGtksMjiTYmOu9LEJw__&Key-Pair-Id=APKAJAGZ7VMH2PFPW6UQ",
      "type": "mp3",
      "size": 23061732,
      "size_pretty": "23.1 MB",
      "duration": 1441.332245,
      "duration_pretty": "24m"
    }
  }
}
type: string
Specify the user agent to be used in the moment of extract the content of the target URL.
Normally you don't need to specify this value but some websites can be different output based on User Agent.
Some websites can serve image format on WebP when they detect you are browsing using Chrome:
curl https://api.microlink.io/?url=https://vimeo.com/188175573&userAgent=Chrome%20mobile
type: boolean
default false
By default the API will be cache consecutive API calls. See cache section for more information.
This parameter has been designed to invalidate the cache responses, avoiding the minimum time necessary to revalidate them.
Providing it, you are forcing to invalidate the current state of the cache for the response and generate a new one.