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