Metadata

Metadata extraction with Microlink API requires only one parameter: the target url.

Metadata detection is enabled by default, so the standard fields are returned even when you do not pass meta explicitly.

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://github.com/microlinkhq' URL:

CLI Microlink API example

microlink https://github.com/microlinkhq

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq')

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://github.com/microlinkhq"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://github.com/microlinkhq"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://github.com/microlinkhq"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://github.com/microlinkhq")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq')

Run the request and look for normalized fields such as title, description, image, logo, and url inside data.

That is the base flow: Microlink fetches the page, detects normalized metadata from the available markup, and returns a structured JSON payload you can reuse in previews, feeds, automation, or indexing workflows.

MQL installation

To run the JavaScript examples with MQL, install @microlink/mql:

npm install @microlink/mql --save

It works in Node.js, Edge runtimes, and the browser. See the MQL installation guide for the environment-specific setup.

If you are using another language, you do not need to install MQL to follow this guide. You can use the terminal examples or call the API directly from any HTTP client.

How metadata options work

Because metadata extraction is already enabled, meta: true is usually unnecessary. You only need to pass meta when you want to customize which fields are detected:

{
  url: 'https://github.com/microlinkhq',
  meta: {
    title: true,
    description: true
  }
}

Use the meta object when you want a smaller, more intentional payload. In raw query strings, the same options are expressed with dot notation such as meta.title=true.

The response

The standard metadata fields are returned directly inside the response payload:

{
  "status": "success",
  "data": {
    "title": "microlink.io",
    "description": "Browser as API. microlink.io has 57 repositories available. Follow their code on GitHub.",
    "lang": "en",
    "author": null,
    "publisher": "GitHub",
    "image": {
      "url": "https://avatars.githubusercontent.com/u/29799436?s=280&v=4",
      "type": "png",
      "size": 4118,
      "height": 280,
      "width": 280,
      "size_pretty": "4.12 kB"
    },
    "url": "https://github.com/microlinkhq",
    "logo": {
      "url": "https://github.com/fluidicon.png",
      "type": "png",
      "size": 597,
      "height": 32,
      "width": 32,
      "size_pretty": "597 B"
    }
  }
}

Most workflows read these fields directly from data. Text fields such as title or description are strings, while media fields such as image, logo, and video return richer objects with dimensions, type, and file size.

Choose a metadata workflow

Need	Best option	Why
You want the standard normalized fields	Default `meta` behavior	Fastest way to get titles, descriptions, images, logos, and more
You only need a small subset of fields	`meta` object	Reduces unnecessary detection work and keeps the payload focused
You want more than the standard fields	Combine `meta` with `data`, `iframe`, or `palette`	Keeps the normalized metadata while adding custom or enriched fields

If you already know you only need a few fields, continue with choosing fields.

Start smaller when you know what you need

If you only care about a small subset of metadata, detect just those fields:

CLI Microlink API example

microlink https://github.com/microlinkhq&meta.title&meta.description

cURL Microlink API example

curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "meta.title=true" \
  -d "meta.description=true"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  meta: {
    title: true,
    description: true
  }
})

Python Microlink API example

import requests

url = "https://api.microlink.io/"

querystring = {
    "url": "https://github.com/microlinkhq",
    "meta.title": "true",
    "meta.description": "true"
}

response = requests.get(url, params=querystring)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://api.microlink.io/"

params = {
  url: "https://github.com/microlinkhq",
  meta.title: "true",
  meta.description: "true"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://api.microlink.io/";

$params = [
    "url" => "https://github.com/microlinkhq",
    "meta.title" => "true",
    "meta.description" => "true"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET"
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://api.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://github.com/microlinkhq")
    q.Set("meta.title", "true")
    q.Set("meta.description", "true")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  meta: {
    title: true,
    description: true
  }
})

Selective detection is the biggest speed and payload win for metadata-focused workflows.

See the meta reference and data fields reference for the full field set.

Using the raw URL

You can call the API directly from your browser address bar or any HTTP client:

https://api.microlink.io?url=https://github.com/microlinkhq

That returns JSON. To return just one field directly, such as title or image.url, use embed in delivery and response shaping.

Free tier and API key

The Microlink API works without an API key. You get 25 free requests per day, which is enough to test the full metadata workflow and most of the examples in this guide.

For production usage, you'll usually want a plan. It unlocks features such as configurable TTL, stale-while-revalidate caching, custom headers, and proxy.

To authenticate, pass your API key as the x-api-key header:

CLI Microlink API example

microlink https://github.com/microlinkhq --api-key YOUR_API_TOKEN

cURL Microlink API example

curl -G "https://pro.microlink.io" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -d "url=https://github.com/microlinkhq"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  apiKey: "YOUR_API_TOKEN"
})

Python Microlink API example

import requests

url = "https://pro.microlink.io/"

querystring = {
    "url": "https://github.com/microlinkhq"
}

headers = {
    "x-api-key": "YOUR_API_TOKEN"
}

response = requests.get(url, params=querystring, headers=headers)

print(response.json())

Ruby Microlink API example

require 'uri'
require 'net/http'

base_url = "https://pro.microlink.io/"

params = {
  url: "https://github.com/microlinkhq"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['x-api-key'] = "YOUR_API_TOKEN"
response = http.request(request)

puts response.body

PHP Microlink API example

<?php

$baseUrl = "https://pro.microlink.io/";

$params = [
    "url" => "https://github.com/microlinkhq"
];

$query = http_build_query($params);
$url = $baseUrl . '?' . $query;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "x-api-key: YOUR_API_TOKEN"
    ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    echo $response;
}

Golang Microlink API example

package main

import (
    "fmt"
    "net/http"
    "net/url"
    "io"
)

func main() {
    baseURL := "https://pro.microlink.io"

    u, err := url.Parse(baseURL)
    if err != nil {
        panic(err)
    }
    q := u.Query()
    q.Set("url", "https://github.com/microlinkhq")
    u.RawQuery = q.Encode()

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("x-api-key", "YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  apiKey: "YOUR_API_TOKEN"
})

You can enter your API key in any interactive example by clicking the key icon in the terminal toolbar.

Throughout this guide, features that require a plan are marked inline.

See the authentication and rate limit docs for details.

What's next

Pick the next step based on the result you want:

Choosing fields — request only the normalized fields you actually need.
Extending results — add custom fields, oEmbed HTML, color palettes, or site analysis.
Delivery and response shaping — keep the full JSON payload, filter it down, or return one field directly.
Page preparation — handle SPAs, dynamic pages, waits, and browser rendering behavior.
Caching and performance — tune freshness, cache behavior, and request speed.
Private pages — extract metadata from logged-in or header-dependent pages safely.
Troubleshooting — fix missing fields, wrong variants, timeouts, and blocked sites.