## Table of Contents

- [Choosing fields](#choosing-fields)
- [Start with the default field set](#start-with-the-default-field-set)
- [Include only specific fields](#include-only-specific-fields)
  - [CLI Microlink API example](#cli-microlink-api-example)
  - [cURL Microlink API example](#curl-microlink-api-example)
  - [JavaScript Microlink API example](#javascript-microlink-api-example)
  - [Python Microlink API example](#python-microlink-api-example)
  - [Ruby Microlink API example](#ruby-microlink-api-example)
  - [PHP Microlink API example](#php-microlink-api-example)
  - [Golang Microlink API example](#golang-microlink-api-example)
- [Exclude heavy or unnecessary fields](#exclude-heavy-or-unnecessary-fields)
  - [CLI Microlink API example](#cli-microlink-api-example-1)
  - [cURL Microlink API example](#curl-microlink-api-example-1)
  - [JavaScript Microlink API example](#javascript-microlink-api-example-1)
  - [Python Microlink API example](#python-microlink-api-example-1)
  - [Ruby Microlink API example](#ruby-microlink-api-example-1)
  - [PHP Microlink API example](#php-microlink-api-example-1)
  - [Golang Microlink API example](#golang-microlink-api-example-1)
- [Include vs exclude](#include-vs-exclude)
- [Media fields are richer objects](#media-fields-are-richer-objects)

---

[](https://microlink.io/docs/api/getting-started/overview)

[API](https://microlink.io/docs/api/getting-started/overview)

[](https://microlink.io/docs/guides)

GUIDES

[](https://microlink.io/docs/mql/getting-started/overview)

MQL

[](https://microlink.io/docs/sdk/getting-started/overview)

SDK

[](https://microlink.io/docs/cards/getting-started/overview)

CARDS

## 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

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

### cURL Microlink API example

``` bash
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

``` javascript
import mql from '@microlink/mql'

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

### Python Microlink API example

``` python
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

``` ruby
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
<?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

``` bash
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))
}
```

``` javascript
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

``` bash
microlink https://github.com/microlinkhq
```

### cURL Microlink API example

``` bash
curl -G "https://api.microlink.io" \
  -d "url=https://github.com/microlinkhq" \
  -d "meta.image=false" \
  -d "meta.logo=false"
```

### JavaScript Microlink API example

``` javascript
import mql from '@microlink/mql'

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

### Python Microlink API example

``` python
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

``` ruby
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
<?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

``` bash
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))
}
```

``` javascript
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](https://microlink.io/docs/api/getting-started/data-fields) for the full shape.

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](https://microlink.io/docs/guides/metadata/page-preparation).
- If the field is site-specific, add a custom fallback with `data` in [extending results](https://microlink.io/docs/guides/metadata/extending-results).

Learn how to add custom fields, embed HTML, palettes, and other enriched outputs in [extending results](https://microlink.io/docs/guides/metadata/extending-results).