# SEO Configuration
# Introduction
The basic 1search query string is not search engine friendly nor human-readable. It's too complex for search engine crawlers to figure out how to auto-fill fields in the URL to increase the visibility of other related search pages. Apart from this, Googlebot does not follow URLs with parameters as it can cause problems with how much the parameters require from the crawler. The crawlers only follow static URLs, which is why the SEO format must be provided so that the crawler bots do not reject the queries.
1search SEO translation feature is here to solve those problems in order to boost SEO performance and user experience.
For example this query:
Find all books with Genre as History, and series as WW2
Query URL without SEO translation feature:
baseUrl/v4/search?q=(C.Genre.History._.Series.WW2.)&sr
SEO query URL:
baseUrl/History/WW2
Currently, we support aspect, range, and POI.
# How Does it Work?
Once the SEO configuration is set up, upon running the SEO generator a map will be created that can be used to convert regular query strings into SEO-friendly URLs, and SEO-friendly URLs back into query strings.
# Aspect
Config the aspects we want to include in SEO and SEO value formatting rules. The formatting rule is used to generate the SEO value according to aspect value. "(value)" will be replaced with facet value. DefaultFacetFormattingRule will be used if there is no formatting rule for a specified aspect. You can also add filter AspectTreeQuery to facets that you want to use to generate SEO records.
{
"AllowedAspects": [
"Genre",
"Series"
],
"RuleBasedFormatterOptions": {
"DefaultFacetFormattingRule": {
"Format": "(value)"
},
"FacetFormattingRules": {
"Genre": {
"Format": "(value)-genre"
}
}
},
"AspectTreeQuery": ""
}
# Range
In theory, there are infinite range values and it not possible to generate SEO for each range value in 1search, so a range value list must be provided to generate SEO records. For each range value, one lower than and greater than the range value SEO record will be generated. For any two range values, one between SEO record will be generated. Same as aspect, default formatting rule would be used if there is no specific one.
{
"AllowedRangeValues": {
"Price": [
"10000",
"20000",
"30000",
"40000",
"50000",
"60000",
"70000",
"80000",
"90000"
]
},
"RuleBasedFormatterOptions": {
"DefaultRangeFormattingRule": {
"Format": "(value)",
"OnlyLowerFormat": "over-(lower)",
"OnlyUpperFormat": "under-(upper)",
"SameValueFormat": "between-(lower)-(upper)",
"BothValueFormat": "between-(lower)-(upper)"
},
"RangeFormattingRules": {
"Price": {
"Format": "(value)",
"OnlyLowerFormat": "over-(lower)",
"OnlyUpperFormat": "under-(upper)",
"SameValueFormat": "between-(lower)-(upper)",
"BothValueFormat": "between-(lower)-(upper)"
}
}
}
}
# POI
POI expression has two parts, place and distance. One place list is required with geolocation and radius. The distance value is the same as range value and there could be infinite distance values. One distance value list is required. SEO records will be generated for each poi and distance value provided. POI formatting rule has one special field "DefaultDistance" and you can have special formatting for the default distance value.
# POI List
{
"LocationPois": {
"Postcode": {
"200": {
"Latitude": -35.279236,
"Longitude": 149.118362,
"Radius": 0.0,
"LocationAttributes": {
"State": "NT"
}
},
"221": {
"Latitude": -35.307312,
"Longitude": 149.140442,
"Radius": 0.0
},
"800": {
"Latitude": -12.461969,
"Longitude": 130.844376,
"Radius": 0.0
},
"801": {
"Latitude": -12.461969,
"Longitude": 130.844376,
"Radius": 0.0
}
}
}
}
# POI SEO Configuration
{
"AllowedPoiDistances": {
"Postcode": [
10.0,
25.0,
50.0,
100.0,
250.0,
500.0
]
},
"RuleBasedFormatterOptions": {
"DefaultPoiFormattingRule": {
"Format": "(poi)-(distance)km",
"DefaultDistance": {
"Value": 25,
"Format": "(poi)"
}
},
"PoiFormattingRules": {
"Postcode": {
"Format": "(poi)-(distance)km",
"DefaultDistance": {
"Value": 25,
"Format": "(poi)"
}
}
}
}
}
# Tagger
There could be conflicts between SEO records. For example, aspect Genre, and Author could have the same value "abc". To avoid conflicts, we can add tagger into SEO value. The SEO value would be "abc-genre" for genre and "abc-series" for series. Currently, there are two options for "SeoValueTagger". One is NullSeoValueTagger, no tagging. The other one is ExceptionalSeoValueTagger, it will tag aspect name as a suffix by default and disable tagging by adding index into "ExceptionalAspects".
"SeoValueTagger": "" // ExceptionalSeoValueTagger or NullSeoValueTagger
"ExceptionalAspects": [
"Genre",
"Series"
]
# Other Configuration
- "OrdersTemplate" defines the index order in SEO. There is one constrain that child aspect must be right after its parent aspect, because we don't support query which only has child aspect.
- FollowDepth is the SEO depth threshold whether you want search engine to index. "null" means not configured.
- SeoValueFormatterOptions - By default, SEO formatting rule only keep letters or digits. You can retain some characters with SeoValueFormatterOptions.
{
"OrdersTemplate": "/Genre/Series/Author",
"FollowDepth" : 5,
"SeoValueFormatterOptions":{
"Joiner": "-",
"ExtraWhitespaces": "{}[]()<>-+/\\&*|:;_!^?", // Character treated as whitespace
"ExtraCharsToRetain": ".",
"PrefixesToRetain": "$",
"SuffixesToRetain": "+"
}
}
# Cron Expression
A cron expression defines how often the SEO generator should be run and when it should be run. It is in the format. The cron expression can be configured within the infra section of the client portal under the title "Generator Cron Expression".
Seconds Minutes Hours DayOfMonth Month DayOfWeek Year
Year is an optional parameter.
# Example
0 15 10 * * ?
The above example means that the generator should run every day at 10:15am. The ?
character means every whereas the * character means to ignore that spot
For more detail on and more examples of a cron expression, see here (opens new window)
You can have multiple SEO configuration within one 1search with different keys and access with sq={key}|
# How to Update SEO
Use client portal API. put http://clientportal.{region_code}.{env}.1search.csnglobal.net/portal/{client}/{service}
For more information on how to use the client portal see ClientPortal Usage
# How to Generate SEO
SEO will be regenerated every night. Call http://clientportal.{region_code}.{env}.1search.csnglobal.net/Generator/{client}/{service}/generate to run it manually.
The SEO generator can also be run from the Client Portal in the SEO section.
# Configuration Full Example
{
"Books": {
"AllowedAspects": [
"Genre",
"Series",
"Microwaveable"
],
"AllowedRangeValues": {
"Price": [
"5",
"10",
"15",
"20",
"25",
"30"
]
},
"AllowedPoiDistances": {
"Postcode": [
10,
25,
50,
100,
250,
500
]
},
"ExceptionalAspects": [
"Genre",
"Series",
"Microwaveable"
],
"AspectTreeQuery": "",
"OrdersTemplate": "/Genre/Series/Microwaveable",
"RuleBasedFormatterOptions": {
"DefaultFacetFormattingRule": {
"Format": "(value)"
},
"DefaultRangeFormattingRule": {
"Format": "(value)",
"OnlyLowerFormat": "over-(lower)",
"OnlyUpperFormat": "under-(upper)",
"SameValueFormat": "between-(lower)-(upper)",
"BothValueFormat": "between-(lower)-(upper)"
},
"DefaultPoiFormattingRule": {
"DefaultDistance": {
"Value": 25,
"Format": "(poi)"
},
"Format": "(poi)-(distance)km"
},
"FacetFormattingRules": {
"Genre": {
"Format": "(value)-genre"
},
"Series": {
"Format": "(value)-series"
}
},
"RangeFormattingRules": {
"Price": {
"Format": "(value)",
"OnlyLowerFormat": "over-(lower)",
"OnlyUpperFormat": "under-(upper)",
"SameValueFormat": "between-(lower)-(upper)",
"BothValueFormat": "between-(lower)-(upper)"
}
}
}
}
}
