If you have an entry with a zip code, you would do the following in the
changeset file:

<entryname="myZipcode"><string>10072</string></entry>

When defining a geoloc dimension, you associate the name of the entry with
the type of geographic data it represents. For example, if the changeset uses
zipcode data, like the previous example, then the dimension file would be
configured like so:

<dimensionid="location"zipcode="myZipcode"type="geoloc"/>

Likewise, if the changeset uses latitude and longitude data, the dimensions file
would look like the following:

If you do not specify names for zip code or latitude/longitude, the Discovery
Engine defaults to naming them “zipcode”, “latitude” and “longitude”.
This means the simplest definition for a geoloc dimension is as follows:

<dimensionid="location"type="geoloc"></dimension>

The sample dataset contains zip codes for 50 real estate listings. A basic query
for all listings in the 10072 zip code looks like this:

The exactDistance setting determines how the Discovery Search Engine decides an
exact match. The setting defines a radius, in miles, from the location being
searched. All items whose location falls within that radius are considered exact
matches.

In this example, we want to consider all items within 1 mile of the location we
were searching for to be considered exact.

In the first example, only the first two listings were considered exact matches,
but you can see in the following response that now all of the listings are
considered exact. Everything else has remained the same.

The normalDistance setting tells the Discovery Search Engine how to calculate the
relevance scores of listings that fall outside a given radius. Just like the
exactDistance setting, a value is set that defines a radius, in miles,
around the location being searched.

The response shows a result set very similar to the first example, but in this
case, the relevance scores are much lower for those listings whose location
falls outside of the radius defined in the query.

The response from this search looks similar to the first example in terms of
exact matches and relevance scores. The big difference is with the
totalSize in the result. In this particular
example, there are only six listings within .5 miles of the 10072 zip code and
those are the only items returned by the Discovery Search Engine.

Mutex dimensions are for values that are mutually exclusive of each other. In
the example dataset, the type dimension is a mutex dimension which means
that a listing can be either a rental or a sales property, but never
both.

There are two properties in the example dataset that are specifically identified
as single-family homes, and you can see in the
response that these two properties are listed first. Notice that all matches are
exact, but only the first two listings have a relevance score of 1.0.

The relevance score is calculated according to each listing’s proximity to the
style searched for. After listings whose style is
single-family, listings of styles that are children of single-family
are listed.

ID

Style

31

single-family

6

single-family

10

classical

15

victorian

19

contemporary

In the first example, single-family is a parent node, at the top of the
tree. The next query searches for homes whose style is federal, a style much
lower in the hierarchy.

The following table shows the styles of the items in the response. The reason
they are not considered exact matches is because the listings that follow the
first two have styles that are either parents of or siblings to the federal
style. In the first example, the listings that followed were children of
single-family.

ID

Style

11

federal

36

federal

10

classical

35

classical

12

greek

In the final example, we will search for homes whose style is capecod. The
query also establishes a page size of 10 in order to retrieve a longer list of
results in order to illustrate how the engine traverses the tree when
calculating relevance scores.

You can see from the following table that the Discovery Search Engine first returns
exact matches – those homes whose style is capecod, following by matches
of the direct parent of the capecod style, colonial. This is followed
by the sibling newengland. Finally, once all the siblings have been
returned, then listings whose style is single-family are returned, the style
that is the direct parent of colonial.

The weight of a criterion is used to calculate the relevance value of a
listing relative to that criterion. In the following example, a query is being
executed for a three bedroom home whose style is a townhome.

The response indicates that there are no listings that are exact matches. There
are two items whose style is townhome, but neither of them have three
bedrooms. Therefore all of the relevance scores are less than 1.0.

In the next example, the relevance score for the style of the listing is lowered
from the default value of 1.0 to be 0.5. This means that whether a
listing is a townhome or not is not as important as whether it should have
three bedrooms.

The response includes the same list of items as the previous search held, but
the relevance scores are higher. This is because the second
query says that whether a listing is a townhome or not is less important.
As a consequence, the relevance scores for townhomes are higher than they were
in the original query.

When a search is executed against the Discovery Search Engine, a list of IDs are
returned. In a typical integration, these IDs are often used to generate a
second HTTP request to retrieve the data associated with the ID. The Discovery
Engine’s renderParameters setting is designed to simplify the second HTTP
request by generating a query string that can be used in an HTTP GET
request.

The first example shows a request that specifies the use of a ‘,’ delimiter to
separate the list of itemIds.