elasticsearch/docs/reference/ingest/apis/put-ip-location-database.asciidoc

[[put-ip-location-database-api]]
=== Create or update IP geolocation database configuration API
++++
<titleabbrev>Create or update IP geolocation database configuration</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-ingest[Ingest APIs].
--

Creates or updates an IP geolocation database configuration.

IMPORTANT: The Maxmind `account_id` shown below requires a license key. Because the license key is sensitive information,
it is stored as a <<secure-settings,secure setting>> in {es} named `ingest.geoip.downloader.maxmind.license_key`. Only
one Maxmind license key is currently allowed per {es} cluster. A valid license key must be in the secure settings in order
to download from Maxmind. The license key setting does not take effect until all nodes are restarted or a
<<cluster-nodes-reload-secure-settings, `reload_secure_settings`>> request is executed.

[source,console]
----
PUT _ingest/ip_location/database/my-database-1
{
  "name": "GeoIP2-Domain",
  "maxmind": {
    "account_id": "1234567"
  }
}
----
// TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]

IMPORTANT: The IPinfo configuration shown below requires a token. Because the token is sensitive information,
it is stored as a <<secure-settings,secure setting>> in {es} named `ingest.ip_location.downloader.ipinfo.token`. Only
one IPinfo token is currently allowed per {es} cluster. A valid token must be in the secure settings in order
to download from IPinfo. The token setting does not take effect until all nodes are restarted or a
<<cluster-nodes-reload-secure-settings, `reload_secure_settings`>> request is executed.

[source,console]
----
PUT _ingest/ip_location/database/my-database-2
{
  "name": "standard_location",
  "ipinfo": {
  }
}
----
// TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]


[[put-ip-location-database-api-request]]
==== {api-request-title}

`PUT /_ingest/ip_location/database/<database>`

[[put-ip-location-database-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.


[[put-ip-location-database-api-path-params]]
==== {api-path-parms-title}

`<database>`::
+
__
(Required, string) ID of the database configuration to create or update.

[[put-ip-location-database-api-query-params]]
==== {api-query-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]

[[put-ip-location-database-api-request-body]]
==== {api-request-body-title}

// tag::ip-location-database-object[]
`name`::
(Required, string)
The provider-assigned name of the IP geolocation database to download.

`<provider>`::
(Required, a provider object and its associated configuration)
The configuration necessary to identify which IP geolocation provider to use to download
the database, as well as any provider-specific configuration necessary for such downloading.
+
At present, the only supported providers are `maxmind` and `ipinfo`. The maxmind provider
requires that an `account_id` (string) is configured. The ipinfo provider does not require
additional configuration in the request body.
// end::ip-location-database-object[]

[[ip-location-database-configuration-licensing]]
==== Licensing

Downloading databases from third party providers is a commercial feature that requires an
appropriate license. For more information, refer to https://www.elastic.co/subscriptions.