# Distance Scoring

Suppose you are searching for a hotel in a certain town but you have a budget limit and if there is no hotel in the town you are searching for, you would rather book the hotel in a town nearby. So basically, there is a tradeoff between price and distance. You would like Results that match your criterion (for example, "hotel, town, non-smoker") to be scored with respect to distance to the town center and also the price.

To introduce this kind of bias to your search result the original score of your search result can be multipied with a factor that decays with distance from your desired result. For the low budged hotel for example, you would prefere low prices, so the higher the price, the less likely you are to check into this hotel so your would require the distance function to score accorinf from the price distance to 0. Furthermore, the farther the hotel is from the town center, the less likely you are to check in, so here the distance is the euclidean distance from the town center.

You can plot these two parameters, price and distance from twon center on a 2d plot and then think about what your tradeoff would look like. For example, your tradeoff function could look like this:

[Insert Gauss function here with some hotels and their weight factor]

In this example, hotel 1 which is very close to the town center but rather expensive would be scored like hotel 2, which is not as expensive as hotel 1 but a little farther from the town center.

##Usage
###Scoring with only one field

To use the distance scoring, you first must define which numeric fields should be used for scoring.
In the above example, the fields might be called "price" for the price of the hotel and "location" for the coordinates of this hotel.
Next, you have to define two values for each field; reference and scale.

The reference is the reference point por the query. For example, if you are a low budget traveller, you probably want the price to be low and can simply set the reference to 0 as in the above example. However, you might also have a higher budget or book your honeymoon, in which case you probebly require higher stadards and might think the hotel should cose something like 200/night.
For the place, the reference is the point that the hotel should be close to, for example a conference you are attending or the town center, or a particular beach.

The scale, roughly speaking, is the amount distance you would allow the query to deviate from your reference point. For the honeymoon example, you might want to spend something like 200/night but you would allow spend a little more or less, say for example 50/night.

As for the deviation from the place, you coul for example think that all within walking distance from your preferred place is OK and since you are rather well trained, walking distance is 2km for you.

To use the distance scoring, your query has to be embedded in a distance_score query like this:

	curl 'localhost:9200/_search' -d '{
		"query" : {
			"distance_score" : {
				"query" : {
    				 "match": { "properties": "balcony, non-smoking" }				},
 				"gauss" : {
    				"location" : {
						"mean": [11 12],
						"scale" : "2km"
					},
					"price" : {
						"mean": "0",
						"scale" : "20"
					}
				}
			}
 		}
	}'

The "gauss" means that the function used will be an unnormalized 2d gaussian of the form

<a href="http://www.codecogs.com/eqnedit.php?latex=\exp(-\frac{x-\mu}{\sigma^2})" target="_blank"><img src="http://latex.codecogs.com/gif.latex?\mathcal{S}(doc)=\exp(-\frac{location_{doc}-\mu_l}{\sigma^2_l})\exp(-\frac{price_{doc}-\mu_p}{\sigma^2_p})" title="\exp(-\frac{x-\mu}{\sigma^2})" /></a>

(insert image here)

## Supported fields
Currently, only single valued fields are supported.

##What is a field is missing?