elasticsearch/docs/reference/ml/anomaly-detection/functions/ml-geo-functions.asciidoc

["appendix",role="exclude",id="ml-geo-functions"]
= Geographic functions

The geographic functions detect anomalies in the geographic location of the
input data.

The {ml-features} include the following geographic function: `lat_long`.

NOTE: You cannot create forecasts for {anomaly-jobs} that contain geographic
functions. You also cannot add rules with conditions to detectors that use
geographic functions. 

[discrete]
[[ml-lat-long]]
== Lat_long

The `lat_long` function detects anomalies in the geographic location of the
input data.

This function supports the following properties:

* `field_name` (required)
* `by_field_name` (optional)
* `over_field_name` (optional)
* `partition_field_name` (optional)

For more information about those properties, see the
{ref}/ml-put-job.html#ml-put-job-request-body[create {anomaly-jobs} API].

.Example 1: Analyzing transactions with the lat_long function
[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/example1
{
  "analysis_config": {
    "detectors": [{
      "function" : "lat_long",
      "field_name" : "transaction_coordinates",
      "by_field_name" : "credit_card_number"
    }]
  },
  "data_description": {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
--------------------------------------------------
// TEST[skip:needs-licence]

If you use this `lat_long` function in a detector in your {anomaly-job}, it
detects anomalies where the geographic location of a credit card transaction is
unusual for a particular customer’s credit card. An anomaly might indicate 
fraud.

IMPORTANT: The `field_name` that you supply must be a single string that 
contains two comma-separated numbers of the form `latitude,longitude`, a 
`geo_point` field, a `geo_shape` field that contains point values, or a 
`geo_centroid` aggregation. The `latitude` and `longitude` must be in the range 
-180 to 180 and represent a point on the surface of the Earth.

For example, JSON data might contain the following transaction coordinates:

[source,js]
--------------------------------------------------
{
  "time": 1460464275,
  "transaction_coordinates": "40.7,-74.0",
  "credit_card_number": "1234123412341234"
}
--------------------------------------------------
// NOTCONSOLE

In {es}, location data is likely to be stored in `geo_point` fields. For more
information, see {ref}/geo-point.html[`geo_point` data type]. This data type is
supported natively in {ml-features}. Specifically, when pulling data from a
`geo_point` field, a {dfeed} will transform the data into the appropriate
`lat,lon` string format before sending to the {anomaly-job}.

For more information, see <<ml-configuring-transform>>.