URL Metadata API

This API provides access to website’s metadata, such as name, description, image, favicon, url, and so on. This is perfect for generating rich link preview for applications, forums, bots etc.

Endpoint

POST /api/v1/metadata

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description
url	string	Yes	The target website URL (must start with http or https).

Request Examples

cURL

curl -X POST https://heavstal.com.ng/api/v1/metadata \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/metadata', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
  })
});

const res = await response.json();
console.log(res.data.title);

Heavstal SDK

import { search } from '@heavstal/api';

const meta = await search.metadata("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
console.log(`Title: ${meta.data.title} | Image: ${meta.data.image}`);

Python

import requests

url = "https://heavstal.com.ng/api/v1/metadata"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"])

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "data": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "description": "The official video for...",
    "image": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "favicon": "https://www.youtube.com/s/desktop/favicon.ico",
    "site_name": "YouTube"
  }
}

Error Response

{
  "status": "error",
  "error": "Unable to reach the provided URL."
}