The JSON-LD Markup Guide To Local Business Schema

Schema.org…

Love it or hate it, schema is an essential part of optimizing your website for local search. For me, it’s a love-hate relationship.

• Love it – because it takes messy data and displays beautiful rich snippets;
• Hate it – because sometimes it’s just a huge mess! At least I find that to be the case quite often with Microdata markup. Even once I get the markup right, I have to spend a lot of time formatting it so it looks decent on the client’s site.

What is Microdata?

Microdata is an HTML specification, a form of semantic mark-up used to encode data through vocabularies such as schema.org and is a great method for communicating metadata to search engines. Search engines such as Google and Bing use this mark-up to extract information from web pages. The specification is often used to create a “richer” experience for web users via nifty rich snippets and interactive elements.

Example of Local Business Microdata formatting:

<div itemscope="" itemtype="http://schema.org/LocalBusiness">
	<span itemprop="name">Gene's Delicious Donuts</span><br>
	<link itemprop="url" href="http://www.example.com">
	<span itemprop="address" itemscope="" itemtype="http://schema.org/PostalAddress">
		<span itemprop="streetAddress">123 Happy Lane</span><br>
		<span itemprop="addressLocality">Irvine</span>, <span itemprop="addressRegion">CA</span> 
		<span itemprop="postalCode">92618</span>
	</span><br>	
	<a itemprop="telephone" href="tel:+15551112345">(555) 111-2345</a><br>
	<span itemprop="faxNumber">(555) 111-2345</span><br>
	<span itemprop="email">[email protected]</span>
	<link itemprop="logo" href="image/path/file-name.jpg">I 
	<link itemprop="sameAs" href="https://plus.google.com/your-google-url">
	<link itemprop="hasMap" href="https://www.google.com/maps/place/link-to-your-business">
	<span itemprop="geo" itemscope="" itemtype="http://schema.org/GeoCoordinates">
		<meta itemprop="latitude" content="111.00000">
		<meta itemprop="longitude" content="-96.012345">
	</span><br>
	<time itemprop="openingHours" datetime="Mo, Tu, We, Th, Fr 09:00-17:00">9AM - 5PM</time> 
</div>

Example of Google’s Knowledge Graph extracting information from Microdata:

Difficulties with Microdata

Since Microdata often uses visual markup to style actual elements on the page, I often find myself messing with CSS and HTML in an effort to make everything look visually appealing on a client’s website. The unnecessary layout problems created by Microdata result in unproductive use of time that could be spent on other important tweaks.

What is JSON-LD?

JSON-LD is a markup data-linking format that allows for easy embedding of data in a script tag. Unlike Microdata, JSON-LD data runs in the background so to speak. There’s no need to tweak actual HTML elements which creates a much faster experience for marketing professionals. With scripts, there’s no need to worry about a missing opening span or a closing div – everything just works. Think of JSON-LD as a faster, cleaner, more simple delivery vehicle for schema. Search engines love it as they are able to crawl the code with ease to understand the data more quickly.

Benefits of Using JSON-LD

• Nested values – allows for display of complex information in an easy to understand fashion.
• Variable-based – to mark up a new element, simply add a variable.
• Saves a lot of time – visual markup is easy to mess up and difficult to troubleshoot unless you’re experienced with visual editors.
• Easy to mark up reviews – keep the styling on your current reviews without having to make changes to your CSS file.

Types of Useful Local Business Data Available for Markup

For most local businesses, the typical NAP, business hours, and geo-location information are the most important elements. A savvy developer may utilize structured data to include:

• Business Name
• Address
• Phone Number
• Email Address
• Business Hours
• Geo-location Information (coordinates and map)
• Reviews
• Logo
• Business Description
• Social Profile Links via sameAs property.
• Site Name

Additional useful local markup types include:

• Products
• Media (images and videos)
• Events
• Corporate Contacts
• Sitelinks Search Box

A Basic Schema.org Example using JSON-LD for a Local Business

In this basic LocalBusiness example, we are including the business type, PostalAddress, description, business name, telephone, opening hours, geo coordinates and social profile links:

<script type="application/ld+json">
	{
  	"@context": "http://schema.org",
  	"@type": "LocalBusiness",
  	"address": {
    "@type": "PostalAddress",
    "addressLocality": "Irvine",
    "addressRegion": "CA",
    "postalCode":"92618",
    "streetAddress": "123 Happy Lane"
  	},
  	"description": "This is your business description.",
  	"name": "Gene’s Delicious Donuts",
  	"telephone": "555-111-2345",
  	"openingHours": "Mo,Tu,We,Th,Fr 09:00-17:00",
  	"geo": {
    "@type": "GeoCoordinates",
    "latitude": "40.75",
    "longitude": "73.98"
 		}, 			
  	"sameAs" : [ "http://www.facebook.com/your-profile",
    "http://www.twitter.com/your-profile",
    "http://plus.google.com/your-profile"]
	}
</script>

How to Implement schema.org Markup Using JSON-LD for a Local Business

Before I dive right into it, a brief disclaimer:

I am not an expert on schema or JSON-LD and have no affiliation with Google. This article is intended to show you how I personally implement schema in my projects, in hopes that this information will be helpful to you. Please read all of Google’s guidelines carefully prior to implementing similar code. Don’t forget to test, test, test!

It’s also worth pointing out a few helpful links and tools:

• Structured Data Testing Tool – Google’s own tool to help you troubleshoot your code. Use it to test your code before publishing it to your website. I can’t recommend it enough, it’ll make your life so much easier.
• Schema Types Spreadsheet – this amazing resource put together by Phil Rozek and David Deering will pump up your schema. Instead of specifying a LocalBusiness, use this spreadsheet to find your schema type to replace the “@type”: “LocalBusiness”, line. Not sure how to pick the right type? No worries, Phil and David wrote a post to help with this task.
• Structured Data examples by Google – this resource has many explanations and examples of the types of data available for markup.
• Google Webmaster Tools – a properly embedded code will be crawled and displayed in your GWT dashboard. Aaron Bradley, the author of SEOSkeptic confirmed that GWT understands JSON-LD. You can find this section in GWT under Search Appearance > Structured Data.
• A list of structured data markup visualization, validation and testing tools may also come in handy.

Step 1: Determine Your Schema Type

Use Phil and David’s handy spreadsheet to determine which schema type describes your business most accurately – instead of using the generic “LocalBusiness” schema.

Step 2: Customize and Add Your Code Anywhere

Customize our basic example (below) with your own information, including the schema type picked in step 1, then add the code anywhere on your website. It doesn’t matter if you place it in the <head> or the <body> section, Google will have no problem reading the code. Since JSON-LD is a data linking format, there are no additional requests to the server, therefore it doesn’t matter if the script is loaded at the top or bottom of the page – there is no render delaying whatsoever.

Customize your Schema Type:

 "@type": "LocalBusiness",

For example, your @type may read:

"@type": "HVACBusiness",
"@type": "Attorney",
"@type": "Physician",
"@type": "RealEstateAgent",
"@type": "Dentist",

Customize Your Geo Coordinates:

To find your business geo-coordinates search for your business in Google Maps and look at the URL to find the latitude and the longitude. Alternatively, you could use http://www.latlong.net/ to search your business address:

Add a URL:

  "url": "http://www.example.com",

Add a Logo:

  "logo": "http://www.example.com/images/logo.png",

Add Email Contact Info:

  "email":"mailto:[email protected]",

Add Social Profiles:

At this time Google supports Facebook, Twitter, Google+, Instagram, YouTube, LinkedIn and Myspace. To add a new profile, place the URL in quotes and separate by a comma.

"sameAs" : [ "http://www.facebook.com/your-profile",
    "http://www.twitter.com/yourProfile",
    "http://plus.google.com/your_profile"]
 

Link to a Map

"hasMap": "https://www.google.com/maps/place/Sushi+Imari/@33.664141,-117.879423,17z/data=!3m1!4b1!4m2!3m1!1s0x80dcdfaa9f9de2a5:0x48ad2abe6bb60a3b?hl=en",

To get the link to your map, find your business in Google Maps, and grab the code from the bottom right gear icon > Share or Embed Map.

Include Additional Type:

As an optional step for those who would like to include Product Ontology values in their code, include additionalType like so:

"additionalType": "http://www.productontology.org/id/Personal_injury_lawyer",

See the post on LocalVisibilitySystem on how to pick Product Ontology categories and why you’d include it in your schema.

Add Aggregate Rating:

"aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4",
    "reviewCount": "250"
 },

Include Reviews with Aggregate Rating

To add more reviews, simply copy and paste the review item and adjust the aggregate reviewCount and ratingValues. Note that each review has 2 curly brackets and is separated by a comma.

<script type="application/ld+json">
	{
  	"@context": "http://schema.org",
  	"@type": "Dentist",    
  	"name": "Family Dentistry",
    "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4",
    "reviewCount": "2"
 	 },  	
    "review": [
    {
      "@type": "Review",
      "author": "Ellie",
      "datePublished": "2011-04-01",
      "description": "I'm not entirely upset with this office, but the staff at the front desk could have been nicer in letting me know they have nothing available for the next 2 months.",
      "name": "Good services, poor communication",
      "reviewRating": {
        "@type": "Rating",
        "bestRating": "5",
        "ratingValue": "3",
        "worstRating": "1"
      	}
    },
    {
      "@type": "Review",
      "author": "Lucas",
      "datePublished": "2011-03-25",
      "description": "I was finally able to get my old crown replaced with a new, porcelain one at a cost that doesn't break the bank.",
      "name": "Affordable Crowns",
      "reviewRating": {
        "@type": "Rating",
        "bestRating": "5",
        "ratingValue": "5",
        "worstRating": "1"
      }
    }
  ]
}
</script>

Step 3: Test Your Code

Once you have your code, unless you’re already tweaking in Structured Data Testing Tool, go ahead and test it by copying and pasting the code and clicking on Validate.

A green checkmark and the text “All good” will show if the code validates without errors. If for some reason you seen an error, carefully check the syntax to make sure you didn’t miss a comma, a curly bracket or quotations.

Extended Properties JSON-LD Example for a Local Business

To add to our basic example, we’ve included an email address, addtionalType, hasMap, website URL and a logo image link:

<script type="application/ld+json">
	{
  	"@context": "http://schema.org",
  	"@type": "LocalBusiness",
	"additionalType": "http://www.productontology.org/id/Genes_Donuts",
	"url": "http://example.com/",
	"logo": "http://www.example.com/images/logo.png",
	"hasMap": "https://www.google.com/maps/place/link-to-your-business",
	"email": "mailto:[email protected]",
  	"address": {
    	"@type": "PostalAddress",
    	"addressLocality": "Irvine",
    	"addressRegion": "CA",
    	"postalCode":"92618",
    	"streetAddress": "123 Happy Lane"
  	},
  	"description": "This is your business description.",
  	"name": "Gene’s Delicious Donuts",
  	"telephone": "555-111-2345",
  	"openingHours": "Mo,Tu,We,Th,Fr 09:00-17:00",
  	"geo": {
    	"@type": "GeoCoordinates",
   	"latitude": "40.75",
    	"longitude": "73.98"
 		}, 			
  	"sameAs" : [ "http://www.facebook.com/your-profile",
    	"http://www.twitter.com/yourProfile",
    	"http://plus.google.com/your_profile"]
	}
</script>

Note: In this example, the product ontology category is completely made up for demonstration purposes. If this were Randy’s Donuts, they could include their name as additionalType!

A Few Tips to Avoid Errors

If you have little or no web development experience, it’s easy to run into an error when trying to customize the code examples with your own variables. I put together a few tips to help you validate your code without issues:

1. Each item is declared in quotes: “telephone”:
2. Each item type is declared in the following format: “@type”:
3. Compounded entries such as the values within an address will always be placed in curly brackets: “address”: { address values }
4. Each item is separated by a comma “addressLocality”: “Irvine”, “addressRegion”: “CA”
5. Repetitive properties such as multiple openingHours or social media links (sameAs property) are placed in brackets [].
6. Don’t use Microsoft Word to format your code, as this will create formatting errors. I recommend notepad or making the edits in Google’s Testing Tool itself.

JSON-LD Markup Guidelines

Before you get excited and start making up data that is not visually present on your website, be aware that Google doesn’t joke around with Rich Snippet spam. Algorithmic and manual penalties are a possibility when it comes to marking up data that your visitors can’t see.

Guidelines Summary Concerning Local Business Markup

• Data must not deceive or mislead experience for search users.
• Use only the most specific types and property names defined by schema.org.
• Marked-up content must be visible on the page where the script is added.

See Google’s Structured Data Policies for a full list of technical and quality guidelines if you are uncertain of permissible use.

Generally speaking, to stay in the clear – make sure you mark up only the content that’s already visible on your website. For example, if the page contains no reviews, don’t add a script that marks up reviews.

A Couple of FAQs

A few frequently asked questions and answers about implementing schema with JSON-LD:

• Can I include data that is not shown on my website? No, however there are some exceptions. Google typically will not show any data that is not visibly present on your page. In fact, it’s against their guidelines. See the link for more details of permissible uses and exceptions.
• My rich snippets aren’t showing up, how come? Google makes no guarantees that your rich snippets will be displayed.
• Can I use your code examples in my site-wide footer? Yes, as long as you don’t forget to customize your values and each element is actually present visually. Does the footer contain all of the information? Is there a logo link to the same image file?
• How do I format varying openingHours? If your business has different hours for different days, you can specify multiple openingHours on an individual line within enclosed in brackets. For a brief overview of openingHours, see the schema.org specification.  Here’s a quick example of a business that’s open most of the week from 9-5 but takes a half day off on Friday:

"openingHours": [ "Mo-Th 09:00-17:00", "Fr 09:00-12:00" ],

• Can I use this code in WordPress or some other content management system? Yes, the script works anywhere. To insert the code site-wide (to show across all pages) add it to your custom scripts section in the Settings (some themes may not have this). If your theme doesn’t have a scripts area, find the header.php or footer.php file and insert it there.
• Does JSON-LD delay CSS rendering? No. Unlike javascript there is no render delay with a data linking format. This means you can place the code anywhere you like without having to worry about slow loading times. The code will increase your HTML content size, but only by a tiny bit – completely negligible when it comes to page load times.

You just spent way longer reading about JSON-LD than it will actually take you to put it to work for your business. You’ll be way ahead of the curve.

If you work with multiple clients, bookmark this page for quick reference.

Update: Big thanks to Aaron Bradley for his feedback on this post! It appears I got some terminology wrong and missed a couple of things. The article has been updated accordingly.

Any questions? Have you used JSON-LD? Let me know in the comments.