URL Meta

API

You'll need to register and get a free API key to access the API.

URL Meta provides a straight forward API to get meta of any given page on the internet. Following documentation covers the API. If you still have any questions, please reach out team@urlmeta.org.

Auth

URL Meta uses Basic Auth for API access. Which means you'll have to provide an Authorization header with every request you make. For auth, you'll have to use your URL Meta account email as username and API key as password.

Treat your API key as a password. Do not use the API in a client environment like an AJAX call.

Basics

Key Value Help
Endpoint api.urlmeta.org Should always be accessed over https
Method GET

Query Parameters

Key Value Help
url The URL to fetch required Along with scheme i.e: http or https
raw boolean optional Will output the entire source of the fetched page instead of parsed meta

Example

To fetch the meta for https://moin.im, we'll use:

https://api.urlmeta.org/?url=https://moin.im

It is recommended to encode the url value. You can use encodeURIComponent in JavaScript and similar in other environments for this.

Headers

Key Value Help
Authorization Basic<space><Base64 econding of 'email:API key'> required

Example

If your account email is team@example.com and the API key is nfh8y34ouhf389f4t3, the value of Authorization header would become:

Basic dGVhbUBleGFtcGxlLmNvbTpuZmg4eTM0b3VoZjM4OWY0dDM=

Here dGVhbUBleGFtcGxlLmNvbTpuZmg4eTM0b3VoZjM4OWY0dDM= is Base64 encoding of text team@example.com:nfh8y34ouhf389f4t3

Response

The API will always return JSON response unless raw is passed as true. Here's the response schema returned by the API.

{
  "result": {
    "status": "OK"
  },
  "meta": { ... }
}

meta key will contain all the meta parsed from the target page.

Here's an example response:

{
  "result": {
    "status": "OK"
  },
  "meta": {
    "site": {
      "name": "Moin Uddin Personal Website",
      "favicon": "https://moin.im/face.png"
    },
    "description": "I'm Moin Uddin, a web developer for both front and back end. I love to search about new trends and technologies in web and then play with them. Contact Me through this site.",
    "image": "https://moin.im/face.png",
    "title": "Moin Uddin - Software developer from Islamabad"
  }
}

meta will only have the properties available on the given page. Make sure they are available in response before consuming them.

Errors

result.status in response will be ERROR in case there was a problem. The response will look something like:

{
  "result": {
    "status": "ERROR",
    "code": 1,
    "reason": "Parameter 'url' not found",
  }
}

You can expect the following errors from the API.

Error Codes

Code Reason
1 Parameter url not found
2 Provided url is not valid
3 Website does not allow crawling
4 Provided url is out of reach
5 Provided url is not a valid page

Examples

For the sake of examples, we'll use team@example.com and nfh8y34ouhf389f4t3 as credentials.

cURL

curl --compressed -D \
headers -H "Authorization: Basic dGVhbUBleGFtcGxlLmNvbTpuZmg4eTM0b3VoZjM4OWY0dDM" \
-X GET https://api.urlmeta.org/?url=https://moin.im

Node.js

Using the request package from NPM.

We can call the URL Meta API like this:

const request = require('request')

const base64Credentials = Buffer.from('team@example.com:nfh8y34ouhf389f4t3').toString('base64')
const options = {
  url: 'https://api.urlmeta.org/?url=https://moin.im',
  headers: {
    'Authorization': 'Basic ' + base64Credentials
  }
}

function callback(error, response, body) {
  if (!error && response.statusCode === 200) {
    let data = JSON.parse(body)

    if (data.result.status == 'OK') {
      console.log(data.meta)
    } else {
      console.log(data.result.reason)
    }
  } else {
    console.log(error, body)
  }
}

request(options, callback)