Navigation
gr_banner_small.png
GoodRelations is a standardized vocabulary for product, price, and company data that can be embedded into existing static and dynamic Web pages.

Project Main Page
Vocabulary
Documentation
Developer's Wiki
GoodRelations Cookbook

Overview

On this page, we explain how you can use GoodRelations to add rich meta-data to your Web pages so that state-of-the art search engines, matchmaking services, and recommender systems will find your company.

GoodRelations is a standardized vocabulary for product, price, and company data that can (1) be embedded into existing static and dynamic Web pages and that (2) can be processed by other computers. This increases the visibility of your products and services in the latest generation of search engines, recommender systems, and other novel applications.

Resources:

Target Audience of this Recipe

  • With this recipe, you describe your company (i.e. the corporation or individual human running the business) and your store location plus opening hours.
  • This is the minimal set of GoodRelations data that any business in the world should expose.
  • This recipe is the simplest of multiple GoodRelations recipes. You may want to check the GoodRelations cookbook; there could be a more specific recipe for your particular vertical domain.
  • You can use the GoodRelations Annotator tool to get a handy snippet of extra markup for simple copy-and-paste.
  • There is growing number of software applications for Web shops or content management that can produce respective data automatically. It may be easier for you to simply install or activate the respective function in your existing software. If your software application is not yet supported, you could also ask your vendor to add the feature and point him to the GoodRelations cookbook (we can offer to help software vendors to implement GoodRelations extensions).

Scenario Description

Basic Data

In the example, we use the following minimal content:

  • The URI of the company's main page is
    http://www.example.com/ (don't forget the trailing slash, i.e. don't use  http://www.example.com)
  • The legal name of the business is
    Hepp's Bagel Bakery Ltd.
  • The address of the shop and the main office are the same.
    • Street and number: 1234 Hepp Road
    • Country: Germany
    • City: Neubiberg
    • Zip code: 85577
    • Region: Bavaria
  • The phone numbers are as follows:
    • Main office: +49-89-6004-0 (+49 is the international prefix for Germany)
    • Shop: +49-89-6004-4217
  • The opening hours given in CET (GMT+1:00) are
    8:00 - 18:00 Mon-Fri and
    8:30-14:00 on Saturdays. 
  • The language of the short text "Hepp's Bagel Bakery Ltd." is English (@en).

Optional Data

If available, you can add the following extra data for your company:

  • URI of the company's logo: logo.png
  • Dun & Bradstreed Number (DUNS): 012345678
  • The Global Location Number (GLN, sometimes also referred to as International Location Number or ILN); a thirteen-digit number used to identify parties and physical locations
    • Main office: 1234567890123
    • Shop: 2345678901234
  • ISIC code for your business: 5610 (code for "Restaurants and mobile food service activities")
  • North American Industry Classification System (NAICS) code for your business: 722110 (code for "Bagel shops, full service")
  • Geo position of your shop (you can easily determine those values for a giving postal address using online services, e.g. the excellent one by Stephen P. Morse at http://stevemorse.org/jcal/latlon.php):
    • Latitude 48.0802626
    • Longitude 11.6407428

Publishing the Rich Meta-Data

There are at least three ways of adding such rich meta-data to your page:

  1. You can simply insert additional, invisible RDFa markup into your HTML page, most likely directly before the closing "body" element. This is the easiest way.
    Important: You must paste the code into the page that is available under the URI http://www.example.com/ or change that string in all examples. On most servers, this is the file index.html or index.htm in the root directory.
  2. You can create a dedicated file "goodrelations.rdf" in the RDF/XML format, upload it to your Web server, and link to that file from your Web page. The necessary steps are described here.
  3. You can create a dedicated textfile "goodrelations.n3" in the N3/Turtle format and proceed as in alternative 2. N3/Turtle is just more readable for humans.

When done, you must tell search engines and indexing services of your new data. To do so, simply paste the URI of the page that contains the snippet (likely http://example.org/) into the respective fields of the following submission pages:

  1. Sindice: http://sindice.com/main/submit
  2. Yahoo SearchMonkey: http://siteexplorer.search.yahoo.com/submit (this requires free registration with Yahoo)
  3. URIBurner: [1]For that service, simply enter the following URI into your browser once you have published your updated page:

UML Diagram

The following shows the relevant subset from the full UML diagram of GoodRelations:

alt UML diagram of the GoodRelations subset for the minimal example

Example in RDFa

Copy-and-paste a snippet into your main Web page

Insert the following additional mark-up directly before the closing </body> in your Web page, i.e.

<xml> ... <body>

Hepp's Bagels are the tastiest you can find on campus.

<div xmlns="http://www.w3.org/1999/xhtml"

 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"

... SNIPPET FROM BELOW ...

</div> </body> </html> </xml>

Snippet for the basic data

Here is the complete snippet to be used for our example:

<xml>

 
   
     
       
       
       
       
       
     
   
   
   
     
       
       
         
           
           
           
           
           
           
           
         
       
       
         
           
           
           
         
       
       
     
   
   
   
   
   
 

</xml>

Snippet for the additional data

Here is the complete snippet to be used for our example if you also have the additional details, like DUNS etc.: <xml>

 
   
     
       
       
       
       
       
     
   
   
   
   
     
       
       
     
   
   
   
   
   
   
     
       
       
       
         
           
           
           
           
           
           
           
         
       
       
         
           
           
           
         
       
       
     
   
   fckLR    
   
   
   
 

</xml>

Updating the XHTML/HTML page header

As a minimal solution, add a "version" attribute with the value "HTML+RDFa 1.0" to the <html> element of your document:

<xml> <html version="HTML+RDFa 1.0" xml:lang="en"> </xml>

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

Your data is, however, 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"

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

2. Add a "version" attribute with the value "XHTML+RDFa 1.0" to the <html> element of your document: <xml> <html version="XHTML+RDFa 1.0" xml:lang="en"> </xml>

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

<xml> <head xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

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

</head> </xml>

Example in N3/Turtle

Create a new text file "goodrelations.n3" with the following content, upload it to your Web server, and link to that file from your Web page. The necessary steps are described here.

N3/Turtle for the basic data

@prefix foo: <http://www.example.com/#> .
@prefix gr: <http://purl.org/goodrelations/v1#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix media: <http://search.yahoo.com/searchmonkey/media/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .

# Part 1: The legal entity (the corporation or person)
foo:myCompany
	a gr:BusinessEntity ;
	gr:legalName "Hepp's Bagel Bakery Ltd. "^^xsd:string ;
   	vcard:fn "Hepp's Bagel Bakery Ltd. "@en ;
	gr:hasPOS foo:myShop ;
	foaf:page <http://www.example.com/> ;
   	vcard:adr foo:address ;
   	vcard:tel "+49-89-6004-0"^^xsd:string ;
	vcard:url <http://www.example.com/>.

# Part 2: Address details using vcard 2006 standard
foo:address a vcard:Address ;
   vcard:country-name "Germany"@en ;
   vcard:locality "Neubiberg"@en ;
   vcard:postal-code "85577"^^xsd:string ;
   vcard:region "Bavaria"@en ;
   vcard:street-address "1234 Hepp Road"@en .

# Part 3: The store or shop
foo:myShop
	a gr:LocationOfSalesOrServiceProvisioning ;
   	vcard:adr foo:address ;
   	vcard:tel "+49-89-6004-4217"^^xsd:string ;
	gr:hasOpeningHoursSpecification
		foo:Workdays, foo:Saturdays .

# Part 4: Opening hours
foo:Workdays
	a gr:OpeningHoursSpecification ;
	gr:opens "08:00:00"^^xsd:time ;
	gr:closes "18:00:00"^^xsd:time ;
	gr:hasOpeningHoursDayOfWeek
		gr:Monday, gr:Tuesday, gr:Wednesday, gr:Thursday, gr:Friday .

foo:Saturdays
	a gr:OpeningHoursSpecification ;
	gr:opens "08:30:00"^^xsd:time ;
	gr:closes "14:00:00"^^xsd:time ;
	gr:hasOpeningHoursDayOfWeek gr:Saturday .


N3/Turtle for the additional data

@prefix foo: <http://www.example.com/#> .
@prefix gr: <http://purl.org/goodrelations/v1#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix media: <http://search.yahoo.com/searchmonkey/media/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .

# Part 1: The legal entity (the corporation or person)
foo:myCompany
	a gr:BusinessEntity ;
	gr:legalName "Hepp's Bagel Bakery Ltd. "^^xsd:string ;
   	vcard:fn "Hepp's Bagel Bakery Ltd. "@en ;
	gr:hasPOS foo:myShop ;
	foaf:page <http://www.example.com/> ;
   	vcard:adr foo:address ;
# Additional properties        <----->
	foaf:depiction <http://www.example.com/files/logo.png> ;
  	media:image <http://www.example.com/files/logo.png> ;
	gr:hasDUNS "012345678"^^xsd:string ;
	gr:hasGlobalLocationNumber "1234567890123"^^xsd:string ;
	gr:hasISICv4 "5610"^^xsd:string ;
	gr:hasNAICS "722110"^^xsd:string ;
	vcard:geo
    	[ vcard:latitude "48.0802626"^^xsd:float ;
         vcard:longitude "11.6407428"^^xsd:float
      	] ;
# End of additional properties <----->
   	vcard:tel "+49-89-6004-0"^^xsd:string ;
	vcard:url <http://www.example.com/>.

# Part 2: Address details using vcard 2006 standard
foo:address a vcard:Address ;
   vcard:country-name "Germany"@en ;
   vcard:locality "Neubiberg"@en ;
   vcard:postal-code "85577"^^xsd:string ;
   vcard:region "Bavaria"@en ;
   vcard:street-address "1234 Hepp Road"@en .

# Part 3: The store or shop
foo:myShop
	a gr:LocationOfSalesOrServiceProvisioning ;
   	vcard:adr foo:address ;
   	vcard:tel "+49-89-6004-4217"^^xsd:string ;
	gr:hasGlobalLocationNumber "2345678901234"^^xsd:string ; # Additional property
	gr:hasOpeningHoursSpecification
		foo:Workdays, foo:Saturdays .

# Part 4: Opening hours
foo:Workdays
	a gr:OpeningHoursSpecification ;
	gr:opens "08:00:00"^^xsd:time ;
	gr:closes "18:00:00"^^xsd:time ;
	gr:hasOpeningHoursDayOfWeek
		gr:Monday, gr:Tuesday, gr:Wednesday, gr:Thursday, gr:Friday .

foo:Saturdays
	a gr:OpeningHoursSpecification ;
	gr:opens "08:30:00"^^xsd:time ;
	gr:closes "14:00:00"^^xsd:time ;
	gr:hasOpeningHoursDayOfWeek gr:Saturday .

Example in RDF/XML

Create a new file "goodrelations.rdf" in the RDF/XML format with the following content, upload it to your Web server, and link to that file from your Web page. The necessary steps are described here.

RDF/XML for the basic data

<xml> <?xml version="1.0"?> <rdf:RDF xmlns:foo="http://www.example.com/#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:xsd="http://www.w3.org/2001/XMLSchema#" xmlns:vcard="http://www.w3.org/2006/vcard/ns#" xmlns:gr="http://purl.org/goodrelations/v1#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:foaf="http://xmlns.com/foaf/0.1/">

  <gr:BusinessEntity rdf:about="http://www.example.com/#myCompany">
     <gr:legalName rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Hepp's Bagel Bakery Ltd. </gr:legalName>
     <vcard:fn xml:lang="en">Hepp's Bagel Bakery Ltd. </vcard:fn>
     <gr:hasPOS>
       <gr:LocationOfSalesOrServiceProvisioning rdf:about="http://www.example.com/#myShop">
          <vcard:adr rdf:resource="http://www.example.com/#address" />
          <vcard:tel rdf:datatype="http://www.w3.org/2001/XMLSchema#string">+49-89-6004-4217</vcard:tel>
          <gr:hasOpeningHoursSpecification>
             <gr:OpeningHoursSpecification rdf:about="http://www.example.com/#Workdays">
               <gr:opens rdf:datatype="http://www.w3.org/2001/XMLSchema#time">08:00:00</gr:opens>
               <gr:closes rdf:datatype="http://www.w3.org/2001/XMLSchema#time">18:00:00</gr:closes>
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Monday" />
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Tuesday" />
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Wednesday" />
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Thursday" />
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Friday" />
             </gr:OpeningHoursSpecification>
          </gr:hasOpeningHoursSpecification>
          <gr:hasOpeningHoursSpecification>
             <gr:OpeningHoursSpecification rdf:about="http://www.example.com/#Saturdays">
               <gr:opens rdf:datatype="http://www.w3.org/2001/XMLSchema#time">08:30:00</gr:opens>
               <gr:closes rdf:datatype="http://www.w3.org/2001/XMLSchema#time">14:00:00</gr:closes>
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Saturday" />
             </gr:OpeningHoursSpecification>
          </gr:hasOpeningHoursSpecification>
       </gr:LocationOfSalesOrServiceProvisioning>
     </gr:hasPOS>
     <foaf:page rdf:resource="http://www.example.com/" />
     <vcard:adr>
       <vcard:Address rdf:about="http://www.example.com/#address">
          <vcard:country-name xml:lang="en">Germany</vcard:country-name>
          <vcard:locality xml:lang="en">Neubiberg</vcard:locality>
          <vcard:postal-code rdf:datatype="http://www.w3.org/2001/XMLSchema#string">85577</vcard:postal-code>
          <vcard:region xml:lang="en">Bavaria</vcard:region>
          <vcard:street-address xml:lang="en">1234 Hepp Road</vcard:street-address>
       </vcard:Address>
     </vcard:adr>
     <vcard:tel rdf:datatype="http://www.w3.org/2001/XMLSchema#string">+49-89-6004-0</vcard:tel>
     <vcard:url rdf:resource="http://www.example.com/" />
  </gr:BusinessEntity>

</rdf:RDF> </xml>

RDF/XML for the additional data

<xml> <?xml version="1.0"?> <rdf:RDF xmlns:foo="http://www.example.com/#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:media="http://search.yahoo.com/searchmonkey/media/" xmlns:xsd="http://www.w3.org/2001/XMLSchema#" xmlns:foaf="http://xmlns.com/foaf/0.1/" xmlns:vcard="http://www.w3.org/2006/vcard/ns#" xmlns:gr="http://purl.org/goodrelations/v1#" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">

  <gr:BusinessEntity rdf:about="http://www.example.com/#myCompany">
     <gr:legalName rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Hepp's Bagel Bakery Ltd. </gr:legalName>
     <vcard:fn xml:lang="en">Hepp's Bagel Bakery Ltd. </vcard:fn>
     <gr:hasPOS>
       <gr:LocationOfSalesOrServiceProvisioning rdf:about="http://www.example.com/#myShop">
          <vcard:adr rdf:resource="http://www.example.com/#address" />
          <vcard:tel rdf:datatype="http://www.w3.org/2001/XMLSchema#string">+49-89-6004-4217</vcard:tel>
          <gr:hasGlobalLocationNumber rdf:datatype="http://www.w3.org/2001/XMLSchema#string">2345678901234</gr:hasGlobalLocationNumber>
          <gr:hasOpeningHoursSpecification>
             <gr:OpeningHoursSpecification rdf:about="http://www.example.com/#Workdays">
               <gr:opens rdf:datatype="http://www.w3.org/2001/XMLSchema#time">08:00:00</gr:opens>
               <gr:closes rdf:datatype="http://www.w3.org/2001/XMLSchema#time">18:00:00</gr:closes>
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Monday" />
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Tuesday" />
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Wednesday" />
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Thursday" />
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Friday" />
             </gr:OpeningHoursSpecification>
          </gr:hasOpeningHoursSpecification>
          <gr:hasOpeningHoursSpecification>
             <gr:OpeningHoursSpecification rdf:about="http://www.example.com/#Saturdays">
               <gr:opens rdf:datatype="http://www.w3.org/2001/XMLSchema#time">08:30:00</gr:opens>
               <gr:closes rdf:datatype="http://www.w3.org/2001/XMLSchema#time">14:00:00</gr:closes>
               <gr:hasOpeningHoursDayOfWeek rdf:resource="http://purl.org/goodrelations/v1#Saturday" />
             </gr:OpeningHoursSpecification>
          </gr:hasOpeningHoursSpecification>
       </gr:LocationOfSalesOrServiceProvisioning>
     </gr:hasPOS>
     <foaf:page rdf:resource="http://www.example.com/" />
     <vcard:adr>
       <vcard:Address rdf:about="http://www.example.com/#address">
          <vcard:country-name xml:lang="en">Germany</vcard:country-name>
          <vcard:locality xml:lang="en">Neubiberg</vcard:locality>
          <vcard:postal-code rdf:datatype="http://www.w3.org/2001/XMLSchema#string">85577</vcard:postal-code>
          <vcard:region xml:lang="en">Bavaria</vcard:region>
          <vcard:street-address xml:lang="en">1234 Hepp Road</vcard:street-address>
       </vcard:Address>
     </vcard:adr>
     <foaf:depiction rdf:resource="logo.png" />
     <media:image rdf:resource="logo.png" />
     <gr:hasDUNS rdf:datatype="http://www.w3.org/2001/XMLSchema#string">012345678</gr:hasDUNS>
     <gr:hasGlobalLocationNumber rdf:datatype="http://www.w3.org/2001/XMLSchema#string">1234567890123</gr:hasGlobalLocationNumber>
     <gr:hasISICv4 rdf:datatype="http://www.w3.org/2001/XMLSchema#string">5610</gr:hasISICv4>
     <gr:hasNAICS rdf:datatype="http://www.w3.org/2001/XMLSchema#string">722110</gr:hasNAICS>
     <vcard:geo>
       <rdf:Description>
          <vcard:latitude rdf:datatype="http://www.w3.org/2001/XMLSchema#float">48.0802626</vcard:latitude>
          <vcard:longitude rdf:datatype="http://www.w3.org/2001/XMLSchema#float">11.6407428</vcard:longitude>
       </rdf:Description>
     </vcard:geo>
     <vcard:tel rdf:datatype="http://www.w3.org/2001/XMLSchema#string">+49-89-6004-0</vcard:tel>
     <vcard:url rdf:resource="http://www.example.com/" />
  </gr:BusinessEntity>

</rdf:RDF> </xml>

Extensions and Improvements

Determine the geographical position of your offices and stores

You can attach the address and geo position of your main office and of your shop or shops to the respective elements, even if you don't know the latitude and longitude of your addresses. Simply use  free online services to determine them, e.g. the excellent one by Stephen P. Morse at http://stevemorse.org/jcal/latlon.php.

Adding multiple stores

Simply add two or more gr:hasPOS properties from the gr:BusinessEntity and define more than one gr:LocationOfSalesOrServiceProvisioning nodes.

Add information on products, services, and payment options

If you want to be more specific on what products or services your are offering, you may want to use the following extended recipes:

  • Recipe 4: Simple Example: Minimal example plus a broad description of what you offer plus payment and deliveryoptions (status: to be completed)
  • Recipe 5: Comprehensive Example: Describing individual products or services including prices etc. (status: to be completed)

Query Example

List the stores and closing hours for Saturdays for all companies with a legal name starting with "Hepp" located in a city staring with "Neubiberg".

PREFIX vcard: <http://www.w3.org/2006/vcard/ns#>

SELECT ?x ?name ?street ?city ?closes WHERE
{?x a gr:BusinessEntity.
OPTIONAL {?x gr:legalName ?name.}
?x gr:hasPOS ?store.
?store gr:hasOpeningHoursSpecification ?spec.
?store vcard:adr ?adr.
?adr vcard:street-address ?street.
?adr vcard:locality ?city.
?spec gr:hasOpeningHoursDayOfWeek gr:Saturday.
?spec gr:closes ?closes.
OPTIONAL {?store rdfs:label ?name.}
FILTER (regex(?name, "^hepp", "i"))
FILTER (regex(?city, "^neubiberg", "i"))
}