ExUrlbox

A light wrapper for the Urlbox API written in Elixir. ExUrlbox's documentation could be found on HexDocs.

Compatible with Urlbox API:v1

A list of options that you can pass into ExUrlbox.get/3, ExUrlbox.post/3, ExUrlbox.head/3, and ExUrlbox.delete/3 can be found here: https://urlbox.io/docs/options

Installation

This package can be installed by adding ex_urlbox to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_urlbox, "~> 0.4.0"}
  ]
end

Configure the Urlbox API Key and Secret

You can find your API Key and Secret here.

Environment Vars (.env) -- refer to (.env.example)

URLBOX_API_KEY="YoUrApIKeY"
URLBOX_API_SECRET="YoUrApISeCreT"

ExUrlbox will automatically look for the env vars listed above using the config below

config :ex_urlbox,
  api_key: {:system, "URLBOX_API_KEY"},
  api_secret: {:system, "URLBOX_API_SECRET"}

Example Usage

GET - Synchronous

# Simple
ExUrlbox.get("https://anthonymineo.com")

# With options:
ExUrlbox.get("https://anthonymineo.com", [format: "png", full_page: true])

# With a timeout (5s):
ExUrlbox.get("https://anthonymineo.com", [], 5_000)


# Extract data from a response
{:ok, screenshot} = ExUrlbox.get("https://anthonymineo.com")

screenshot.body
# => <<137, 80, 78, 71, 13, ...>>>

screenshot.headers
# => [{"content-type", "image/png"}, ...]

screenshot.url
# => https://api.urlbox.io/v1/:apikey/hmac(:apisecret)/png?url=https%3A%2F%2Fwww.google.com&width=1024&height=768

POST - Async with a webhook

Post a request to Urlbox for a screenshot. You should provide a webhook_url option to receive a postback to once the screenshot render is complete.

# Example request with options containing `webhook_url` for a postback:
ExUrlbox.post("https://anthonymineo.com", [webhook_url: "https://app-waiting-for-incoming-post.com/"])

Initial response from a post:

{
  "renderId": "ebcbce5q-9657-435f-aeb6-5db207ee87b5",
  "status": "created",
  "statusUrl": "https://api.urlbox.io/render/ebcbce5q-9657-435f-aeb6-5db207ee87b5"
}

Example postback to webhook_url:

{
  "event": "render.succeeded",
  "renderId": "ebcbce5q-9657-435f-aeb6-5db207ee87b5",
  "result": {
    "renderUrl": "https://renders.urlbox.io/urlbox1/renders/a1d7g7d45f7am5a0a69cd3de/2022/5/7/ebcbce5q-9657-435f-aeb6-5db207ee87b5.png",
    "size": 34748
  },
  "meta": {
    "startTime":"2022-05-07T20:25:28.879Z",
    "endTime":"2022-05-07T20:25:31.646Z"
  }
}

NOTE: If you dont provide a webhook_url you will need to poll the statusUrl that's included in the initial post response for the status of your request:

/* GET => statusUrl */
{
  "renderId": "ebcbce5q-9657-435f-aeb6-5db207ee87b5",
  "status":	"succeeded",
  "renderUrl": "https://renders.urlbox.io/urlbox1/renders/a1d7g7d45f7am5a0a69cd3de/2022/5/7/ebcbce5q-9657-435f-aeb6-5db207ee87b5.png",
  "size": 34748
}

DELETE

Urlbox will cache previously created screenshots for some time. Sending a delete request removes a previously created screenshot from the cache.

Example request:

ExUrlbox.delete("https://anthonymineo.com")

HEAD

If you just want to get the response status/headers without pulling down the full response body.

Example request:

ExUrlbox.head("https://anthonymineo.com")

Docs

The full docs can be found at https://hexdocs.pm/ex_urlbox.

Documentation has been generated with ExDoc and published on HexDocs.