Overview: How Can I Use GoodRelations?

The GoodRelations Cookbook
Recipe Quickstart
Description How can I use GoodRelations - the fastest way to get GoodRelations up and running
Status mature
Level beginner
Tags publication, rich markup, rdfa
See also http://www.ebusiness-unibw.org/wiki/GoodRelations

Web Shop Software

For many popular shop applications (e.g. Magento, Joomla/Virtuemart, Wordpress/WPEC,...), there exist free extension modules that make adding GoodRelations RDFa for semantic SEO as easy as a few mouse-clicks. That is by far the simplest way of adding GoodRelations to your site, so make sure you check the current list of available modules first.

If your software package is not listed there, you can:

  1. Ask your vendor to add GoodRelations using this recipe. We provide free support for this!
  2. Export your catalog in BMEcat syntax and use this tool. This is mainly interesting for manufacturers or very large shops.
  3. Add GoodRelations to your templates manually as shown below.

Static Store, Restaurant, or Company Page

The easiest way is to use the on-line snippet generator tool that creates the markup for GoodRelations automatically - ready for copy-and-paste.

Alternatively, you can add the markup manually, as shown below.

HTML Patterns for Rich Markup

In this section, you find ready-to-use snippets for adding rich meta-data about a company, a store, or a product / offer to existing Web pages.

It's incredibly simple:

  1. Customize and insert the patterns of additional HTML markup into your Web pages.
  2. Add links between the patterns.
  3. Modify the header information of the respective pages.

That's it. You will be all set.

Company

Insert the additional HTML markup given below anywhere in the body section of your main Web page and fill the following elements with your correct data:

  • "Hepp's Bagel Bakery Ltd. ": The official legal name of your company or business.
  • "Germany": Your country.
  • "Munich": The city in which your business is registered.
  • "85577": The zip code of your residence.
  • "1234 Main Street": The street and number of your residence
  • "+1 408 970-6104": The phone number, including the international prefix.
  • "http://www.hepps-bagels.com/image_or_logo.png": The Web address (URL) of a logo or image.
<!-- in RDFa 1.1, you can use the abbreviation:
<div profile="http://www.heppnetz.de/grprofile/">
-->
<div xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="http://www.w3.org/1999/xhtml"
xmlns:foaf="http://xmlns.com/foaf/0.1/"
xmlns:gr="http://purl.org/goodrelations/v1#"
xmlns:vcard="http://www.w3.org/2006/vcard/ns#">
 
<div about="#company" typeof="gr:BusinessEntity">
<div property="gr:legalName" content="Hepp's Bagel Bakery Ltd."></div>
<div rel="vcard:adr">
<div typeof="vcard:Address">
<div property="vcard:country-name" content="Germany"></div>
<div property="vcard:locality" content="Munich"></div>
<div property="vcard:postal-code" content="85577"></div>
<div property="vcard:street-address" content="1234 Main Street"></div>
</div>
</div>
<div property="vcard:tel" content="+1 408 970-6104"></div>
<div rel="foaf:depiction" resource="http://www.hepps-bagels.com/image_or_logo.png">
</div>
<div rel="foaf:page" resource=""></div>
</div>
</div>

Statistics:

  • 16 lines of markup
  • less than 1000 characters of extra code

Shop, Restaurant, or Store, and Opening Hours

Insert the additional HTML markup given below anywhere in the body section of the Web page describing your shop(s), restaurant(s), or store(s), and fill the following elements with your correct data:

  • "Pizzeria La Mamma": The name of the store or location.
  • "Germany": Your country.
  • "Munich": The city for the location.
  • "85577": The zip code for the location.
  • "1234 Main Street": The street and number for the location.
  • "+33 408 970-6104": A phone number, including the international prefix.
  • "http://www.pizza-la-mamma.com/image_or_logo.png": The Web address (URL) of a logo or image.
  • "48.08" / "11.64": The geo position of the store as longitude and latitude (Unknown? Find it here!).
  • "08:00:00" / "18:00:00": The opening hours for Monday through Friday.
  • "08:30:00" / "14:00:00": The opening hours for Saturday.

If you have multiple shops, but just one page, simply copy the snippet multiple times and replace  all ocurrences of the three elements

  • "#store", "#mon_fri", and "#sat"

inside the same snippet by

  • "#store1", "#mon_fri1", and "#sat1"
  • "#store2", "#mon_fri2", and "#sat2"
  • "#store3", "#mon_fri3", and "#sat3"

etc.

<!-- in RDFa 1.1, you can use the abbreviation:
<div profile="http://www.heppnetz.de/grprofile/"> -->
<div xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="http://www.w3.org/1999/xhtml"
xmlns:foaf="http://xmlns.com/foaf/0.1/"
xmlns:gr="http://purl.org/goodrelations/v1#"
xmlns:vcard="http://www.w3.org/2006/vcard/ns#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#">
 
<div about="#store" typeof="gr:Location">
<div property="gr:name" content="Pizzeria La Mamma"></div>
<div rel="vcard:adr">
<div typeof="vcard:Address">
<div property="vcard:country-name" content="Germany"></div>
<div property="vcard:locality" content="Munich"></div>
<div property="vcard:postal-code" content="85577"></div>
<div property="vcard:street-address" content="1234 Main Street"></div>
</div>
</div>
<div property="vcard:tel" content="+33 408 970-6104"></div>
<div rel="foaf:depiction" resource="http://www.pizza-la-mamma.com/image_or_logo.png">
</div>
<div rel="vcard:geo">
<div>
<div property="vcard:latitude" content="48.08" datatype="xsd:float"></div>
<div property="vcard:longitude" content="11.64" datatype="xsd:float"></div>
</div>
</div>
<div rel="gr:hasOpeningHoursSpecification">
<div about="#mon_fri" typeof="gr:OpeningHoursSpecification">
<div property="gr:opens" content="08:00:00" datatype="xsd:time"></div>
<div property="gr:closes" content="18:00:00" datatype="xsd:time"></div>
<div rel="gr:hasOpeningHoursDayOfWeek"
resource="http://purl.org/goodrelations/v1#Friday"></div>
<div rel="gr:hasOpeningHoursDayOfWeek"
resource="http://purl.org/goodrelations/v1#Thursday"></div>
<div rel="gr:hasOpeningHoursDayOfWeek"
resource="http://purl.org/goodrelations/v1#Wednesday"></div>
<div rel="gr:hasOpeningHoursDayOfWeek"
resource="http://purl.org/goodrelations/v1#Tuesday"></div>
<div rel="gr:hasOpeningHoursDayOfWeek"
resource="http://purl.org/goodrelations/v1#Monday"></div>
</div>
</div>
<div rel="gr:hasOpeningHoursSpecification">
<div about="#sat" typeof="gr:OpeningHoursSpecification">
<div property="gr:opens" content="08:30:00" datatype="xsd:time"></div>
<div property="gr:closes" content="14:00:00" datatype="xsd:time"></div>
<div rel="gr:hasOpeningHoursDayOfWeek"
resource="http://purl.org/goodrelations/v1#Saturday"></div>
</div>
</div>
<div rel="foaf:page" resource=""></div>
</div>
</div>

Statistics:

  • 41 lines of markup
  • less than 2,500 characters of extra code

Offer / Product

Insert the additional HTML markup given below anywhere in the body section of your Web page template for individual products, and fill the following elements with the correct data for the respective product:

  • "Canon Rebel T2i (EOS 550D) $899" : The name of the product.
  • "The Rebel T2i EOS 550D is Cannon's top-of-the-line ...": The long description of the product.
  • xml:lang="en": Replace "en" by the ISO 639-1 code for the language of the name or description if the text is not in English.
  • "013803123784": The EAN-13, 13-digit UPC, or 13-digit ISBN code for the product. This code is now officially called GTIN-13. 10-digit ISBNs and 12-digit UPC codes can be converted, see here for converting ISBNs. Converting 12-digit UPCs into GTIN13 is simpler, just add a preceeding zero.
    That code is optional for GoodRelations, but highly recommended, since it increases the visibility of your items a lot.
  • "USD" and "899": The currency and price for the product (899 US$ in our example). Use 3-letter ISO 4217 codes for currencies, e.g. EUR for euro.
<!-- in RDFa 1.1, you can use the abbreviation:
<div profile="http://www.heppnetz.de/grprofile/"> -->
<div xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="http://www.w3.org/1999/xhtml"
xmlns:foaf="http://xmlns.com/foaf/0.1/"
xmlns:gr="http://purl.org/goodrelations/v1#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#">
 
<div about="#offering" typeof="gr:Offering">
<div property="gr:name" content="Canon Rebel T2i (EOS 550D) $899" xml:lang="en"></div>
<div property="gr:description" content="The Rebel T2i EOS 550D is Cannon's
top-of-the-line consumer digital SLR camera.
It can shoot up to 18 megapixel resolution photos and features an ISO range of 100-6400.
Now just $ 899 $" xml:lang="en"></div>

<div rel="foaf:depiction"
resource="http://a.img-dpreview.com/previews/CanonEOS550D/images/intro.jpg">
</div>
<div rel="gr:hasBusinessFunction" resource="http://purl.org/goodrelations/v1#Sell">
</div>
<div property="gr:hasEAN_UCC-13" content="013803123784" datatype="xsd:string"></div>
<div rel="gr:hasPriceSpecification">
<div typeof="gr:UnitPriceSpecification">
<div property="gr:hasCurrency" content="USD" datatype="xsd:string"></div>
<div property="gr:hasCurrencyValue" content="899" datatype="xsd:float"></div>
</div>
</div>
<div rel="gr:acceptedPaymentMethods"
resource="http://purl.org/goodrelations/v1#PayPal"></div>
<div rel="gr:acceptedPaymentMethods"
resource="http://purl.org/goodrelations/v1#MasterCard"></div>
<div rel="foaf:page" resource="http://myshop.com/canon-rebel-t2i/"></div>
</div>
</div>
Add additional or delete existing lines of the form
<div rel="gr:acceptedPaymentMethods"
resource="http://purl.org/goodrelations/v1#PayPal"></div>
for indicating the accepted payment methods. The following payment methods are currently supported by GoodRelations:

If you have multiple products within the same Web page, simply copy the snippet multiple times and replace  all occurrences of the element

  • "#offer"

inside the same snippet by

  • "#offer1"
  • "#offer2"
  • "#offer3"
Important: When the page sets the base address (URI) using
<base href="...">
to something different from the actual product detail page URI (e.g. to the main page), then you must use the full URI of the page plus the respective hash fragment ""#offer", e.g.
<div about="http://myshop.com/canon-rebel-t2i/#offer" typeof="gr:BusinessEntity">
For more info, see here.

Statistics:

  • 18 lines of markup
  • less than 1,500 characters of extra code

Connecting the Dots – Linking the Data

Once you have added the structured data to the Web page markup, you have to link them so that search engines and recommender system can find them. Two types of links are important:

  1. Links from offers / products to the company.
  2. Links from the company to its stores / restaurants.

Linking from Offers / Products to the Company

1. Find out the final main Web address (URL) under which the page with the company markup will be available.

Examples:

If there are multiple ways to access the page, use the shortest and most official one. Let's assume it is

in our example.

Now add "#company" to that address, which gives us

as the identifier for the company data.

2. Insert the following additional line to the data markup for each product / offer page:

<div rev="gr:offers" resource="http://www.hepps-bagels.com/#company"></div>

Instead of http://www.hepps-bagels.com/#company, use the correct URL determined in step 1.

This additional line must follow directly after the element

<div about="#offering" typeof="gr:Offering">
So the correct markup in our example would be
<div about="#offering" typeof="gr:Offering">
<div rev="gr:offers" resource="http://www.hepps-bagels.com/#company"></div>
<div property="gr:name"
content="Canon Rebel T2i (EOS 550D) $899" xml:lang="en"></div>
...

Linking from the Company to its Stores / Shops / Restaurants.

1. Determine the complete Web address (URL, including "#company") of the company as before. In our example, we use

as the identifier for the company data.

2. Insert the following additional line to the data markup for each store page:

<div rev="gr:hasPOS" resource="http://www.hepps-bagels.com/#company"></div>

Instead of http://www.hepps-bagels.com/#company, use the correct URL determined in step 1.

This additional line must follow directly after the element

<div about="#store" typeof="gr:Location">
So the correct markup in our example would be
<div about="#store" typeof="gr:Location">
<div rev="gr:hasPOS" resource="http://www.hepps-bagels.com/#company"></div>
<div property="gr:name" content="Pizzeria La Mamma"></div>
...

Updating the XHTML/HTML Page Header

Minimal Solution

Add a "xmlns" attribute with the value "http://www.w3.org/1999/xhtml" and a "version" attribute with the value "XHTML+RDFa 1.0" to the <html> element of your document:

<html xmlns="http://www.w3.org/1999/xhtml" version="XHTML+RDFa 1.0" xml:lang="en">

This is enough for basic access to your rich meta-data.

XHTML 1.0 Strict and XHTML 1.1

Your data is much more visible and useful if your page is compliant with the XHTML 1.0 strict specification. If you meet that requirement, you should instead update the page header as follows:

1. Change the DOCTYPE in the header to "XHTML+RDFa"

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"
"http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
2. Add a "xmlns" attribute with the value "http://www.w3.org/1999/xhtml" and a "version" attribute with the value "XHTML+RDFa 1.0" to the <html> element of your document:
<html xmlns="http://www.w3.org/1999/xhtml" version="XHTML+RDFa 1.0" xml:lang="en">

3. Check that the <head> element includes the proper content type and encoding for XHTML:

<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<title>Your page title blabla...</title>
</head>

XHTML 1.0 Transitional

a) Set DOCTYPE to XHTML+RDFa 1.0:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"
"http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">

b) Set html version attribute to XHTML+RDFa1.0

<html xmlns="http://www.w3.org/1999/xhtml" version="XHTML+RDFa 1.0">

HTML5

a) Set DOCTYPE to html

<!DOCTYPE html>

b) Set html version attribute to HTML+RDFa1.1

<html version="HTML+RDFa 1.1" lang="en">

Note that this is only a W3C Working Draft at this stage, but should work nonetheless.

See also: http://answers.semanticweb.com/questions/1187/can-i-use-the-html5-doctype-with-rdfa

HTML 4.x

Either use HTML5 recipe or simply set the html version attribute to HTML+RDFa1.1 or XHTML+RDFa1.0. Most clients will extract RDF from this type.

<html xmlns="http://www.w3.org/1999/xhtml" version="XHTML+RDFa 1.0">

or

<html version="HTML+RDFa 1.1">

Further Information

Remarks

  • We use vcard:tel with plain literals in those examples, since this is the form expected by Yahoo. This is in part contradicting the official VCard Ontology specification but maximizes the visibility of your data. Should Google or any other major application require the official VCard modeling, we will change the recipe accordingly. Currently, Google recommends its own vocabulary and "tel" property.