Overview of the Embed API

The Embed API allows you to embed certain content from Plug.events into your own site. The process of embedding is based on tokens, where each token corresponds to a search result in a space, with optional filters. For example you can get a token that corresponds to all Salsa dance events in France for the next 15 days. When you use the token to embed those results on your own site, your visitors will see the upcoming Salsa dance events in France.

You must have an organization on Plug.events to use the feature. Create one from the Create menu if needed.

How to set up a token

1. First use Plug.events to search for events. Specifically:

  • The search must use an interest or a place, and cannot be anything anywhere. (It can be anything in a certain place, or an interest anywhere.)
  • If a geographic search suits you better, first search at the city level then choose Search Nearby.

2. Once you have the results showing (either a direct search on a space or a Search Nearby), press Share, then press “Embed in your web site”.

3. In the next screen, choose your organization and enter the request, explaining briefly where you will be embedding content. Press Request Embed Token.

4. It will take some time to process the request, and we will email you when it is approved.

5. After it is approved, go to manage.plug.events, select the same organization, then navigate to the API Embed Tokens page.

6. Press Edit (next to your token), and update any of the settings:

  • Webmaster status: You must set it to Active to be able to use the token
  • Output format: Choose the output that best suits your needs. More information on each format is shown below.
  • Timezone: Ensure the timezone is appropriate for your viewers. Note that we are only showing dates, but the timezone can still affect which day is displayed.

7. Once you save the token, you will see instructions for using it. You can return to the instructions later from the Use Token button.

HTML Page option

When you select HTML Page as the output format, we will produce the page for you. This is the simplest option. You can set up your site in one of two ways:

  • A simple link, which opens the listing in a new page. This is not very useful because you can also just send users to see the list on Plug.events, but you can at least use this to check how it will look when embedded.
  • An iframe, which allows content from another site to appear on your page. The iframe code is given to you in the instructions.

When using an iframe, feel free to change the styling. The sample given shows “width:80%;height:400px”, and you can change the width to a different percent, or to a number like 340px, so that the iframe size fits where you need on your page layout.

HTML Fragment option

When you select HTML Fragment as the output format, we will produce the styled page fragment for you, and then you write code to put that fragment anywhere on your page. This involves some javascript code, but has some advantages:

  • You can override the default styles to match those on your page
  • You can flow the content around images and other elements on the page, instead of being constrained to an iframe rectangle with a scroll bar.

To override styles, you will need a background in CSS:

  • Use your browser’s developer tools to inspect the fragment. Notice that there is a <style> element which contains our default styles, followed a div element with class=”plug-root”.
  • Check the class names used in the fragment. Some of them are plug-event, plug-event-name, and plug-event-venue.
  • Add styles to your page after the ones defined in the fragment.

JSON option

The JSON option is the most developer-friendly, since the data come to you as a javascript array, and you can use the data values to format output as you like. Note that our terms of use require that you display the results, and not store them.

The JSON object is defined like this:

//typescript type
interface Root {
  events: {
    status - a code indicating cancelation status. 5=live, 9=canceled
    createdAt - the ISO formatted date in UTC when the event was created
    modifiedAt - the ISO formatted date in UTC when the event was last modified
    slug: string, //unique event identifier (normally not displayed)
    name: string, //event name
    description: string, //event description
    bannerImage: string|null, //URL of the banner image, if any
    isExpanded: boolean, //true if this is a primary result, recommending the image be displayed
    plugUrl: string, //URL to view the event detail on Plug.events
    timeDisplay: string|null, //displayable date
    startDateTimeIso: string, //start date-time in ISO format, UTC timezone
    endDateTimeIso: string, //end date-time in ISO format, UTC timezone
    timezone: string|null, //IANA timezone code for the event
    isAllDay: boolean, //if true, the time portion of the start/end times should be ignored
    publishedByName: string|null, //name of publishing organization
    publishedByOrgSlug: string|null, //identifier of publishing organization
    priceDisplay: string|null, //displayable price or price range with currency symbol
    isFree: boolean, //true means it is a free event
    currency: string|null, //symbol for the currency, such as '$'
    lowPrice: number|null, //low price if known
    highPrice: number|null, //high price if known
    venueAddress: string|null, //address
    venueLocale: string|null, //structured place name of venue
    venueName: string|null //venue name
    eventFormat - the code for the event type
    eventFormatDisplay - the English text for the event type
  }[],
  eventListUrl: string, //URL to send users to see the full list on Plug.events
  plugLogoUrl: string, //Plug logo, required to display
  poweredByMessage: string //powered by message, required to display
}