# url

**required**

Type: \<string\>

The target URL for getting information based on the content.

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

### CLI Microlink API example

```
microlink https://kikobeats.com
```

### cURL Microlink API example

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

### JavaScript Microlink API example

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

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

### Python Microlink API example

```
import requests

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

querystring = {
    "url": "https://kikobeats.com"
}

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://kikobeats.com"
}

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://kikobeats.com"
];

$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://kikobeats.com")
    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://kikobeats.com')

Click to run the code and see the API response

The url parameter is the only required parameter for any Microlink API request.

## [URL requirements](https://microlink.io/docs/api/parameters/url#url-requirements)

The URL provided must be:

- **Publicly reachable** by the service (no localhost or private IPs)
- **Well-formed** following the standard
- **Including protocol** (http:// or https://)

If you want to extract content behind a login panel, the URL provided should contain the authentication step as part of the query string, or provide the authentication credentials using [headers](https://microlink.io/docs/api/parameters/headers).

## [URL encoding](https://microlink.io/docs/api/parameters/url#url-encoding)

If the URL provided has query string parameters, they should be properly escaped to not interfere with the Microlink API query parameters.

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

### CLI Microlink API example

```
microlink https://kikobeats.com?ref=microlink
```

### cURL Microlink API example

```
curl -G "https://api.microlink.io" \
  -d "url=https://kikobeats.com?ref=microlink"
```

### JavaScript Microlink API example

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

const { data } = await mql('https://kikobeats.com?ref=microlink')
```

### Python Microlink API example

```
import requests

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

querystring = {
    "url": "https://kikobeats.com?ref=microlink"
}

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://kikobeats.com?ref=microlink"
}

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://kikobeats.com?ref=microlink"
];

$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://kikobeats.com?ref=microlink")
    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://kikobeats.com?ref=microlink')

Click to run the code and see the API response

URLs with query parameters are automatically encoded.

Using or [Microlink CLI](https://microlink.io/docs/api/getting-started/cli) will escape the URL properly. Otherwise, you need to escape it using [](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)

encodeURIComponent

or equivalent.

## [Protocol handling](https://microlink.io/docs/api/parameters/url#protocol-handling)

The protocol matters: If the target URL has relative URLs inside (e.g., images or videos), then the URL provided will be used to resolve relative URLs into absolute.

This means that if you provide HTTPS, then all relative URLs will be resolved under SSL.

## [Common URL patterns](https://microlink.io/docs/api/parameters/url#common-url-patterns)

Here are examples of different URL types you can process:

**Standard websites**

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

Click to run the code and see the API response

**URLs with fragments**

The following examples show how to use the Microlink API with CLI, cURL, JavaScript, Python, Ruby, PHP & Golang, targeting 'https://microlink.io/docs/api/getting-started/overview#url-requirements' URL:

### CLI Microlink API example

```
microlink https://microlink.io/docs/api/getting-started/overview#url-requirements
```

### cURL Microlink API example

```
curl -G "https://api.microlink.io" \
  -d "url=https://microlink.io/docs/api/getting-started/overview#url-requirements"
```

### JavaScript Microlink API example

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

const { data } = await mql('https://microlink.io/docs/api/getting-started/overview#url-requirements')
```

### Python Microlink API example

```
import requests

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

querystring = {
    "url": "https://microlink.io/docs/api/getting-started/overview#url-requirements"
}

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://microlink.io/docs/api/getting-started/overview#url-requirements"
}

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://microlink.io/docs/api/getting-started/overview#url-requirements"
];

$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://microlink.io/docs/api/getting-started/overview#url-requirements")
    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://microlink.io/docs/api/getting-started/overview#url-requirements')

Click to run the code and see the API response

**Internationalized domain names**

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

### CLI Microlink API example

```
microlink https://例え.jp
```

### cURL Microlink API example

```
curl -G "https://api.microlink.io" \
  -d "url=https://例え.jp"
```

### JavaScript Microlink API example

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

const { data } = await mql('https://例え.jp')
```

### Python Microlink API example

```
import requests

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

querystring = {
    "url": "https://例え.jp"
}

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://例え.jp"
}

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://例え.jp"
];

$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://例え.jp")
    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://例え.jp')

Click to run the code and see the API response

## [Error handling](https://microlink.io/docs/api/parameters/url#error-handling)

If the URL cannot be processed, you'll receive one of these error codes:

- **EINVALURL**: The URL format is invalid
- **EFORBIDDENURL**: The URL resolves to a forbidden IP range
- **EMAXREDIRECTS**: Too many redirects (more than 10 hops)
- **ETIMEOUT**: The URL took too long to respond

See [error codes](https://microlink.io/docs/api/basics/error-codes) for the complete list.