## Table of Contents

- [Metadata](#metadata)
  - [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)
- [MQL installation](#mql-installation)
- [The response](#the-response)
- [Start smaller when you know what you need](#start-smaller-when-you-know-what-you-need)
  - [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)
- [Using the raw URL](#using-the-raw-url)
- [Free tier and API key](#free-tier-and-api-key)
  - [CLI Microlink API example](#cli-microlink-api-example-2)
  - [cURL Microlink API example](#curl-microlink-api-example-2)
  - [JavaScript Microlink API example](#javascript-microlink-api-example-2)
  - [Python Microlink API example](#python-microlink-api-example-2)
  - [Ruby Microlink API example](#ruby-microlink-api-example-2)
  - [PHP Microlink API example](#php-microlink-api-example-2)
  - [Golang Microlink API example](#golang-microlink-api-example-2)
- [What's next](#whats-next)
- [See also](#see-also)

---

[](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

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

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

### cURL Microlink API example

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

### JavaScript Microlink API example

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

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

### Python Microlink API example

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

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

``` 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")
    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')
```

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

``` bash
npm install @microlink/mql --save
```

It works in Node.js, Edge runtimes, and the browser. See the [MQL installation guide](https://microlink.io/docs/mql/getting-started/installation) 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.

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:

``` js
{

  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:

``` json
{

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

| 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](https://microlink.io/docs/guides/metadata/choosing-fields).

## Start smaller when you know what you need

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

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

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

### JavaScript Microlink API example

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

const { data } = await mql('https://github.com/microlinkhq', {
  meta: {
    title: true,
    description: 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"
}

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"
}

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"
];

$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")
    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

  }

})
```

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

See the [meta reference](https://microlink.io/docs/api/parameters/meta) and [data fields reference](https://microlink.io/docs/api/getting-started/data-fields) for the full field set.

## Using the raw URL

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

``` bash
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](https://microlink.io/docs/guides/metadata/delivery-and-response).

## Free tier and API key

The Microlink API works without an API key. You get **50 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

PRO

plan. It unlocks features such as [configurable TTL](https://microlink.io/docs/api/parameters/ttl), [stale-while-revalidate caching](https://microlink.io/docs/api/parameters/staleTtl), [custom headers](https://microlink.io/docs/api/parameters/headers), and [proxy](https://microlink.io/docs/api/parameters/proxy).

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 'apiKey' API parameter:

### CLI Microlink API example

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

### cURL Microlink API example

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

### JavaScript Microlink API example

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

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

### Python Microlink API example

``` python
import requests

url = "https://api.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

``` ruby
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)
request['x-api-key'] = "YOUR_API_TOKEN"
response = http.request(request)

puts response.body
```

### PHP Microlink API example

``` php
<?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",
    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

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

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

PRO

plan are marked inline.

See the [authentication](https://microlink.io/docs/api/basics/authentication) and [rate limit](https://microlink.io/docs/api/basics/rate-limit) docs for details.

## What's next

Pick the next step based on the result you want:

- **[Choosing fields](https://microlink.io/docs/guides/metadata/choosing-fields)** — request only the normalized fields you actually need.
- **[Extending results](https://microlink.io/docs/guides/metadata/extending-results)** — add custom fields, oEmbed HTML, color palettes, or site analysis.
- **[Delivery and response shaping](https://microlink.io/docs/guides/metadata/delivery-and-response)** — keep the full JSON payload, filter it down, or return one field directly.
- **[Page preparation](https://microlink.io/docs/guides/metadata/page-preparation)** — handle SPAs, dynamic pages, waits, and browser rendering behavior.
- **[Caching and performance](https://microlink.io/docs/guides/metadata/caching-and-performance)** — tune freshness, cache behavior, and request speed.
- **[Private pages](https://microlink.io/docs/guides/metadata/private-pages)** — extract metadata from logged-in or header-dependent pages safely.
- **[Troubleshooting](https://microlink.io/docs/guides/metadata/troubleshooting)** — fix missing fields, wrong variants, timeouts, and blocked sites.

## See also

- [Data extraction](https://microlink.io/docs/guides/data-extraction) — if you need custom fields beyond the normalized metadata set.
- [Screenshot](https://microlink.io/docs/guides/screenshot) — if you need a visual capture alongside or instead of metadata.
- [Insights](https://microlink.io/docs/guides/insights) — if you want to analyze the technology stack or run a Lighthouse audit.