OpenGraph

Usage

Using OpenGraph Ninja is easy as cake. Let's get you set up in a few simple steps!

There are several ways to use this service - directly through the API or via a library.

  • Vanilla JS library
  • React library

Use an automatic script

The easiest way to get nice-looking APIs is to include couple of tags in your <head />:

<script defer src="https://unpkg.com/@opengraphninja/sdk/dist/sdk.cjs.production.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@opengraphninja/sdk/styles.css" />

Then, run window.OpenGraphNinja.initialize() to initialize the script.

This will turn all <a />-tags inside <p />-tags into nice-looking previews. Note that this will only affect code inside your <main /> section, so make sure you have one of those!

There are plenty of ways to customize the behavior. Please refer to the docs.

Use the React library

If you're working with a React application, we have created a component and a custom hook for you to use. Install the@opengraphninja/react package, and use the PreviewLink component wherever you want a preview.

There are lots of more details and examples in the docs.

Use the API

If you want even more control over how the previews are generated or displayed, you can use the API directly.

We only have one endpoint, and that endpoint is /api/v1?url=my-site.com. Specify the URL you want to scrape in the url query parameter, and wait for the results. The API accepts URLs with and without the protocol (http://or https://).

$ curl https://opengraph.ninja/api/v1?url=url-to-scrape.com

We will cache any response for an hour.

A successful response will look like this:

$ curl http://localhost:3000/api/v1?url=apple.com
{
  "hostname": "apple.com",
  "title": "Apple",
  "description": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, and expert device support.",
  "image": {
    "url": "https://www.apple.com/ac/structured-data/images/open_graph_logo.png?201809210816",
    "alt": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, and expert device support."
  },
  "details": {
    "ogTitle": "Apple",
    "ogDescription": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, and expert device support.",
    "ogUrl": "https://www.apple.com/",
    "ogLocale": "en_US",
    "ogType": "website",
    "ogSiteName": "Apple",
    "ogImage": {
      "url": "https://www.apple.com/ac/structured-data/images/open_graph_logo.png?201809210816",
      "width": null,
      "height": null,
      "type": "png"
    },
    "charset": "utf8"
  }
}

We'll try to give you sane error messages if anything goes wrong. You'll get the correct HTTP status code, and a body with an error message explaining what went wrong.

OpenGraph Ninja © 2022