Choosing fields

The default metadata payload is a great starting point, but most production workflows do better when they only request the fields they actually use.

Start with the default field set

By default, Microlink can return fields such as:

title
description
lang
author
publisher
date
url
image
logo
video

This is the right choice when you are exploring a new source or building a generic preview card system that needs a broad set of metadata.

Include only specific fields

Use a meta object with true values when you know exactly which fields you want:

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

CLI Microlink API example

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

cURL Microlink API example

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

JavaScript Microlink API example

import mql from '@microlink/mql'

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

Python Microlink API example

import requests

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

querystring = {
    "url": "https://github.com/microlinkhq",
    "meta.title": "true",
    "meta.description": "true",
    "meta.image": "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",
  meta.image: "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",
    "meta.image" => "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")
    q.Set("meta.image", "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,
    image: true
  }
})

This keeps the response focused on the three fields you actually care about.

This pattern is ideal for search indexing, link previews, or backend jobs that only depend on one or two fields.

Exclude heavy or unnecessary fields

Use false values when you want the default field set except for a few omissions:

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

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" \
  -d "meta.image=false" \
  -d "meta.logo=false"

JavaScript Microlink API example

import mql from '@microlink/mql'

const { data } = await mql('https://github.com/microlinkhq', {
  meta: {
    image: false,
    logo: false
  }
})

Python Microlink API example

import requests

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

querystring = {
    "url": "https://github.com/microlinkhq",
    "meta.image": "false",
    "meta.logo": "false"
}

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.image: "false",
  meta.logo: "false"
}

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.image" => "false",
    "meta.logo" => "false"
];

$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.image", "false")
    q.Set("meta.logo", "false")
    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: {
    image: false,
    logo: false
  }
})

Exclude media fields when you only need text metadata and want to avoid unnecessary payload weight.

This is useful when your workflow needs most of the normalized text fields but not preview images or logos.

Include vs exclude

If you need	Use
Only a few specific fields	Set those fields to `true`
Almost everything except one or two fields	Set those fields to `false`
Maximum visibility while exploring a new site	Leave `meta` at its default behavior

The meta object is the main control surface for metadata extraction performance and payload size.

Media fields are richer objects

Text fields such as title, description, publisher, or lang are returned as strings.

Media fields such as image, logo, and video include more context:

url
type
size
size_pretty
width
height

Playable media can also include duration fields. See the data fields reference for the full shape.

Missing values are signals, not necessarily errors

Some sites simply do not expose every field. For example, author or date can be null even when the request succeeds.

If one field is consistently missing:

Try the default metadata set first, not a narrowed one.
If the site is client-rendered, continue with page preparation.
If the field is site-specific, add a custom fallback with data in extending results.

Next step

Learn how to add custom fields, embed HTML, palettes, and other enriched outputs in extending results.