How to use our API

• Introduction
• Request Structure
• Parameters
• Response Element
• Code Examples
  • PHP
  • JavaScript
  • NodeJS
  • C-Sharp
  • Python

Introduction

You can access our v1 API using the following endpoint:

https://api.opengraphr.com/v1/og

Request structure

To make a request, you will need to include your api_token and the requested url:

GET https://api.opengraphr.com/v1/og?api_token={YOUR_API_TOKEN}&url={YOUR_URL}

By default, our API will cache results for a month, but you can refresh the cache by sending the force=1 parameter:

GET https://api.opengraphr.com/v1/og?api_token={YOUR_API_TOKEN}&url={YOUR_URL}&force=1

Also, we are integrated with TailGraph in a way that, if we don't find the proper Open Graph metatags, we will automatically generate an Open Graph image using their API! To enable this feature, you just have to append tailgraph=1 to the query string.

GET https://api.opengraphr.com/v1/og?api_token={YOUR_API_TOKEN}&url={YOUR_URL}&tailgraph=1

Parameters

This is the list of parameters accepted by our API

Response Element

The API response will be structure as follows. In the JSON root, it will have 4 parameters (if found):

• title: Inferred Open Graph title.
• description: Inferred Open Graph description.
• url: Open Graph URL from og:url. If not provided it will use the request url.
• image: Inferred Open Graph image url.
• reading_time_in_minutes: Time required to read the page in minutes, with an average of 225 words per minute.

Additionally, the raw key will contain every Open Graph metatag that was found, replacing every : by _.

This is an example of the response from our API:

{
  "title": "The New York Times - Breaking News, US News, World News and Videos",
  "description": "Live news, investigations, opinion, photos and video by the journalists of The New York Times from more than 150 countries around the world. Subscribe for coverage of U.S. and international news, politics, business, technology, science, health, arts, sports and more.",
  "image": "https://static01.nyt.com/newsgraphics/images/icons/defaultPromoCrop.png",
  "url": "https://www.nytimes.com",
  "reading_time_in_minutes": 7,
  "raw": {
    "title": "The New York Times - Breaking News, US News, World News and Videos",
    "metadescription": "Live news, investigations, opinion, photos and video by the journalists of The New York Times from more than 150 countries around the world. Subscribe for coverage of U.S. and international news, politics, business, technology, science, health, arts, sports and more.",
    "og_url": "https://www.nytimes.com",
    "og_type": "website",
    "og_title": "The New York Times - Breaking News, US News, World News and Videos",
    "og_description": "Live news, investigations, opinion, photos and video by the journalists of The New York Times from more than 150 countries around the world. Subscribe for coverage of U.S. and international news, politics, business, technology, science, health, arts, sports and more.",
    "og_image": "https://static01.nyt.com/newsgraphics/images/icons/defaultPromoCrop.png",
    "twitter_site": "@nytimes"
  }
}

Code Examples

Get Open Graph tags using PHP

You can easily get the Open Graph information of a given site by using the following script in PHP:

$token = 'YOUR_TOKEN';
$url = 'https://www.nytimes.com/';

$requestUrl = 'https://api.opengraphr.com/v1/og?api_token=' . $token . '&url=' . urlencode($url);
$response = json_decode(file_get_contents($requestUrl), true);

var_dump($response);

Get Open Graph tags using JavaScript

You can easily get the Open Graph information of a given site by using the following script in plain JS:

const token = 'YOUR_TOKEN'
const url = 'https://www.nytimes.com/'

const requestUrl = `https://api.opengraphr.com/v1/og?api_token=${token}&url=${encodeURIComponent(url)}`
fetch(requestUrl)
    .then(response => response.json())
    .then(og => {
        console.table(og)
    })

Get Open Graph tags using NodeJS

You can easily get the Open Graph information of a given site by using the following script in NodeJS:

const axios = require('axios')
const express = require('express')
const app = express()
const token = 'YOUR_TOKEN'

app.get('/site/info', async (req, res) => {
    const { url } = req.query
    const requestUrl = 'https://api.opengraphr.com/v1/og'

    const response = await axios.get(requestUrl, {
        params: {
            url,
            api_token: token,
            // tailgraph: 1,
            // force: 1,
        },
    })
    const og = response.data
    res.json(og)
})

app.listen(3000, function () {
  console.log('Example app listening on port 3000!')
})

Get Open Graph tags using C Sharp

You can easily get the Open Graph information of a given site by using the following script in C#:

using System;
using System.Net;
using System.IO;
using Newtonsoft.Json;

namespace CSharpDemo
{
    class MainClass
    {
        public static void Main (string[] args)
        {
            var token = 'YOUR_TOKEN';
            var url = 'https://www.nytimes.com/';
            var urlEncoded = Uri.EscapeDataString(url);

            var requestUrl = "https://api.opengraphr.com/api/og?api_token=" + token + "&url=" + urlEncoded;

            var request = WebRequest.Create(requestUrl);
            request.ContentType = "application/json;";

            string text;

            var response = (HttpWebResponse)request.GetResponse();

            using (var sr = new StreamReader(response.GetResponseStream()))
            {
                text = sr.ReadToEnd();

                dynamic og = JsonConvert.DeserializeObject(text);

                Console.WriteLine("Title\t\t" + og.title);
                Console.WriteLine("Description\t" + og.description);
                Console.WriteLine("Image\t\t" + og.image);
            }
        }
    }
}

Get Open Graph tags using Python

You can easily get the Open Graph information of a given site by using the following script in Python:

import requests

TOKEN = 'YOUR_TOKEN'
url = 'https://www.nytimes.com/'

endpoint = 'https://api.opengraphr.com/api/og'
response = requests.get(endpoint, params={ 'url': url, 'api_token': TOKEN }).json()
print(response)