Debugging entity matching issues

Matching issues are experimental
We are still working on reporting results from our matching validation system. If a matching issue seems to have been correctly detected, please fix the issue and wait for the next ingestion to validate your fix. If the issue seems to be incorrectly attributed to an entity, please reach out to your Google Contact for support.

Before sending an entity from a feed to the Knowledge Graph, Google tries to determine whether the entity is already present in the Knowledge Graph, in order to avoid creating duplicate items. This process is called matching or reconciliation. If Google has a problem matching--for example, if an entity doesn't have enough information for Google to search for matches, or if the entity almost (but not quite) matches a known item--then Search Console might report a matching issue. If you see a mismatch error that affects a class of items and persists after repeated fix attempts, you might contact your Google representative to confirm whether it really is an error. A matching error doesn't necessarily mean that your suggested entity is incorrect, only that we can't match it to an entity in the Knowledge Graph.

Here is a list of matching issues exposed by the Feed report. Matching issues start with the string "Entity matching" in the Feed report. Note that the term "property" used below refers to a structured data field, not a Search Console property.

General tips:

  • Capitalization is ignored for matching, so you shouldn't see a matching error due to incorrect capitalization. However, if you are providing a new entity, Google may use your name as the official name, so you should try to capitalize the name as you would wish it to appear.
  • Do not include entities in the feed if most of the required properties are not available. For example, if you have neither the episode number nor the original release or air date for a TVEpisode, it's better to exclude such entities from the feed until the required info is secured.
  • For general debugging strategies, read the debugging section of the Feed report guide.
Name matching issues

Google has found an item in the Knowledge Graph that nearly matches an entity from your feed, but the name value is different. Check that you are using the proper name for this entity.

There are the name matching issues shown in the report:

  • Entity name cannot contain the subtitle: The name you provided includes the subtitle of the movie or show. The name property should be only the name, and not include the subtitle. For example, don't specify "Viking Dead: The Lost Viking Fleet Of Roskilde," but rather "Viking Dead".
  • Name contains possibly descriptive term: The name contains descriptive terms that aren't actually part of the title. For example, not "Movie: Red" but "Red".
  • Name contains unnecessary phrase: The name includes other unnecessary phrases that are not part of the official name. For example, not George Washington: The Example History Program" but "The Example History Program".
  • Update the entity name to match the value currently known to Google: Another unspecified naming problem was found. Read the tips below to learn how to fix the issue.

 

Here are some tips for finding the name to match a known property in the Knowledge Graph:

Use an authoritative source for the name

If this is a movie or television show or series, check authoritative sources for the title: for example, the official web page for the movie, IMDB or Wikipedia. We strongly recommend using the sameAs property to provide the URL of your source for the definitive name.

Don't include version dates in the title

For example, "1984" is an appropriate film name, but not "Godzilla (2014)". If you want to distinguish your entity from another Knowledge Graph item with the same name that was released later, use the releasedEvent.startDate property to specify the date. If a TVEpisode lacks a proper name, see here.

Not this But this
{
  "@type": "Movie",
  "@name": "Godzilla (2014)",
...
}
{
  "@type": "Movie",
  "@name": "Godzilla",
  "releasedEvent": {
  "@type": "PublicationEvent",
  "startDate": "2014-05-16"
  }
},

...
}

Don't include the word "Movie" or "Series"

Don't include the words "Movie" or "Series" unless they are actually part of the title, or the item has no proper name. For example:

Not this But this
{
  "@type": "Movie",
  "@name": "Movie: Red",
...
}
{
  "@type": "TVSeries",
  "@value": "Series Friends"
...
}
{
  "@type": "Movie",
  "@name": "Red",
...
}
{
  "@type": "TVSeries",
  "@value": "Friends"
...
}

Provide different titles for different locations

If the movie has different titles in different locations, provide them:

Provide names for different locales
"name": [
  {
    "@language": "en-us",
    "@value": "Airplane!"
  },
  {
    "@language": "en-au",
    "@value": "Flying high?"
  }]

Remove unnecessary punctuation

Remove unnecessary punctuation if they are not part of the official name. This includes | (pipe mark), "quotation marks", -hyphens-, [brackets], (parentheses), and emojis.

For example, not "Cupcakes (the movie)" but simply "Cupcakes"

Remove HMTL entities and escaped Unicode

Don't use HTML entities or Unicode escaping. The only entities that must be escaped are double quotation marks. Other characters, if needed (and they are probably not), can be used directly. Examples:

  • "Get your \"game\" on" (escape needed for " marks)
  • "Lilo & Stitch" (no escape needed)
  • "Ender's Game" (no escape needed)

Use only properly translated names

Provide the name in the released language for this film. After that, you can provide the name in additional languages as part of the name array value.

Do not provide multiple language names in a single string; instead, define a name array and provide the name in each language in a separate array entry.

Do not use an arbitrary translation of the title for different languages. If the movie has an official title in additional languages, you can provide them; otherwise, don't provide unofficial title translations.

Do not transliterate a name from another language into your language.

Not this But this
{
  "name": "Example | Ejemplo"

...

}

"name": [
  {
    "@language": "en",
    "@value": "Example"
  },
  {
    "@language": "es",
    "@value": "Ejemplo"
  }]
{
  "name": "Les Real Housewives d'Orange County"
...
}

Even for a French language provider...

{
  "name": "The Real Housewives of Orange County"
...
}

provide the name in the original show language.

"name": [
  {
    "@language": "cn-hk",
    "@value": "警察故事"},
  {
    "@language": "en",
    "@value": "jing cha gu shi"}
]
"name": "警察故事"

Or

"name": [
  {
     "@language": "cn-hk",
     "@value": "警察故事"},
  {
     "@language": "en",
     "@value": "Police Story"}
]

Provide alternate titles

If official alternate names are available in the same locales, you can use the alternateName property to fix or avoid a matching error.

Not this But this
{
  "name":"Birdman or (The Unexpected Virtue of Ignorance),
...
}
{
  "name":"Birdman",
  "alternateName": "The Unexpected Virtue of Ignorance",
...
}

Don't include additional information in the title

For example, don't include phrases like the following in the name:

  • Online course
  • Documentary
  • (Comedy)
  • [English subtitles]
  • [Japan/US]
  • [Free/Paid programming]

A good rule of thumb: If you have extra information in the movie title and you have a mismatch issue, try removing it.

Not this But this
{
  "name": "The Mask (Comedy)",
...
}
{
  "name": "The Mask",
  "genre": "Comedy",
...
}
{
  "name": "(吹) さまよう刃",
...
}
{
  "name": "さまよう刃",
...
}
{
  "name": "Planet Money Comics: Micro-Face",
...
}
{
  "name": "Micro-Face",
  "partOfSeries": {
    "@type": "TVSeries",
    "@id": "12345", 
    "name": "Planet Money Comics", 
    "sameAs": "https://www.npr.org/transcripts/992365334" },
...
}
{
  "name": "Sherlock Holmes: The Sign of the Four",
...
}
{
  "name": "The Sign of the Four",
...
}
{
  "name": "An evening with Sherlock Holmes"
...
}
{
  "name": "An evening with Sherlock Holmes: Live from Boston"
...
}

💡 Sometimes extra information is correct in a title. Not all extra information is incorrect; check an authoritative source for the official title.

Unnamed TVEpisode entities

If an episode has a proper name, use that. If an episode has no name, use one of the following values for the name, translated into the film's language:

  • Episode <<number>> (Preferred) - Where <<number>> is the episode number.
    • "name": "Episode 2"
    • "name": "2화"
  • Episode YYYY-MM-DD - If there is no episode number, provide the local time original air date in the format YYYY-MM-DD. If there are more than one episodes without names on the same day, provide the time as shown in the next bullet. Examples:
    • "name": "Episode 2018-10-01"
    • "name": "Эпизод 2018-10-01"
  • Episode YYYY-MM-DD HH:MM - Used when there are multiple unnamed episodes during a single day. provide the local time original air date in the format YYYY-MM-DD HH:MM. Examples:
    • "name": "Episode 2018-10-01 20:00"
    • "name": "Эпизод 2018-10-01 20:00"
Not this But this
{
 "@type": "TVEpisode",
 "name": "Season 2: Game changer",
...
}
{
 "@type": "TVEpisode",
 "name": "Game changer",
 "partOfSeason": {
   "@type": "TVSeason", 
   "@id": "12345",
   "seasonNumber": 2 }, 
...
}

{
  "@type": "TVEpisode",
  "name": "Episode 14: The Pilot",
...
}
{
  "@type": "TVEpisode",
  "name": "The Pilot",
  "episodeNumber": 14
...
}
{
  "@type": "TVEpisode"
  "name": "",
  "episodeNumber": "7",
...

}
{
 "@type": "TVEpisode"
 "name": "Episode 7"
 "episodeNumber": 7
...
}

 

or

{
 "@type": "TVEpisode"
 "name": "Épisode 7"
 "episodeNumber": 7
...
}

 

or

{
  "@type": "TVEpisode"
  "name": [
      {
        "@language": "en-us",
        "@value": "Episode 7"
      },
      {
        "@language": "fr",
        "@value": "Épisode 7"
      },
     ],
  episodeNumber: "7"
...
}
Update property <<property_name>> to match the value currently known to Google

Google has found an item in the Knowledge Graph that nearly matches an entity from your feed, but the <<property_name>> value is different. For instance, we might have found a match with a slightly different director value. Check and fix the value of this property in your entity to see if you can make it match the item in the Knowledge Graph.

Check your entity's value to see if it has any unusual or unexpected characters, or perhaps alternate spellings that you might change.

Entity type seems incorrect: Should probably be <<suggested_type>>
The entity type provided in the feed seems to match a similar entity of a different type in the Knowledge Graph. For instance, you provided a TVEpisode entity when we think that you should have specified a Movie entity. Change the implementation of your entity to the suggested type. For example, when changing an entity type from TVEpisode to Movie, you should remove properties like episodeNumber and partOfSeason, and add required or recommended Movie properties.
Set a value for <<property_name>> to match the item known to Google
Google has found an item in the Knowledge Graph that probably matches the entity from your feed, but you should provide us with the suggested property to help us confirm whether our suspected match is correct. Provide the <<property_name>> property in your entity to help Google determine whether your entity is indeed the same as the one we've found in the Knowledge Graph.
Entity has insufficient information to match - add more recommended fields
The entity doesn't have enough information in non-required properties to help Google find a matching entity, if one exists. Please provide more recommended properties for this entity to assist with matching.
Multiple feed entities seem to match the same entity known to Google
Multiple different entities in your feed seem to match the same item in the Knowledge Graph. Remove the duplicates from your feed, or else if these are definitely not identical entities, add additional disambiguating properties, or correct any properties that were incorrectly specified.

Duplicate IDs

The @id property value was repeated multiple times for an entity in the feed, causing the duplicate @id issue. Make sure that the @id property is globally unique (the same ID cannot be repeated for different entities) and also meets the following specifications:

  • The @id must be in Unified Resource Identifier (URI) form.
  • The @id must be static, which means it's stable and doesn't change over time.
  • Your organization must own the domain used for the @id value.

For more information, see the developer documentation about the @id property.

 

 

Was this helpful?

How can we improve it?
true
New to Search Console?

Never used Search Console before? Start here, whether you're a complete beginner, an SEO expert, or a website developer.

Search
Clear search
Close search
Google apps
Main menu