> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de geolocalización IP

> La API de geolocalización IP de Cleariflow es una API JSON RESTful rápida, eficiente y moderna que identifica la ubicación y detalles adicionales de direcciones IP en más de 190 países.

La API funciona con notable sencillez: solo proporcione su clave API junto con una dirección IP y recibirá datos de ubicación completos, incluidos códigos postales, nombres de ciudades, información regional, detalles del país y coordenadas precisas de latitud/longitud.

## Primeros pasos

### Arquitectura REST

Al igual que todas las APIs de Cleariflow, la API de geolocalización IP sigue los principios REST. Emplea URL predecibles orientadas a recursos y utiliza códigos de estado HTTP para indicar errores.

### Seguridad HTTPS

Todas las comunicaciones con la API de geolocalización IP deben estar protegidas mediante protocolos TLS 1.2 o superiores.

### Versionado de la API

Todas las APIs de Cleariflow incorporan versionado. La API de geolocalización IP opera actualmente en la versión 1.

### Autenticación con clave API

Su clave API sirve como credencial de autenticación única para acceder a la API de geolocalización IP de Cleariflow. Es importante tener en cuenta que cada API de Cleariflow requiere una clave API distinta, lo que significa que necesitará claves separadas para distintos servicios como las APIs de geolocalización IP y validación de email. Para autenticar sus solicitudes, añada su clave API a la URL base.

### URL base

```
https://ipgeolocation.cleariflow.com/v1/
```

### Endpoint de geolocalización

La API de geolocalización IP de Cleariflow solo requiere su clave API única y detecta automáticamente la dirección IP del cliente que realiza la solicitud. Alternativamente, puede incluir el parámetro "ip\_address" para especificar una IP concreta para el análisis:

```
https://ipgeolocation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& ip_address = 94.198.41.118 (optional)
```

Esto representa una solicitud exitosa, que devuelve la dirección IP y los detalles asociados a continuación:

<ResponseExample>
  ```json theme={"system"}
  {
      "ip_address": "80.255.13.30",
      "city": null,
      "city_geoname_id": null,
      "region": null,
      "region_iso_code": null,
      "region_geoname_id": null,
      "postal_code": null,
      "country": "Germany",
      "country_code": "DE",
      "country_geoname_id": 2921044,
      "country_is_eu": true,
      "continent": "Europe",
      "continent_code": "EU",
      "continent_geoname_id": 6255148,
      "longitude": 9.491,
      "latitude": 51.2993,
      "security": {
          "is_vpn": true,
          "is_proxy": false,
          "vpn_provider": "NordVPN"
      },
      "timezone": {
          "name": "Europe/Berlin",
          "abbreviation": "CEST",
          "gmt_offset": 2,
          "current_time": "21:21:22",
          "is_dst": true
      },
      "flag": {
          "emoji": "🇩🇪",
          "unicode": "U+1F1E9 U+1F1EA",
          "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
          "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
      },
      "currency": {
          "currency_name": "Euros",
          "currency_code": "EUR"
      },
      "connection": {
          "autonomous_system_number": 201011,
          "autonomous_system_organization": "Core-Backbone GmbH",
          "connection_type": null,
          "isp_name": null,
          "organization_name": null
      }
  }
  ```
</ResponseExample>

### Parámetros de solicitud

<ParamField query="api_key" type="String" required>
  Su clave API única. Tenga en cuenta que cada usuario tiene claves API únicas para cada una de las APIs de Cleariflow, por lo que su clave de la API de geolocalización IP no funcionará para su API de validación de email, por ejemplo.
</ParamField>

<ParamField query="ip_address" type="String">
  La dirección IP a geolocalizar. Se admiten direcciones IPv4 e IPv6. Tenga en cuenta que si deja este parámetro en blanco, el servicio geolocalizará la dirección IP desde la que se realizó la solicitud.
</ParamField>

<ParamField query="fields" type="String">
  Lista separada por comas de claves de **nivel superior** a devolver (por ejemplo, `?fields=country,security`). Para incluir indicadores VPN/proxy, use `security`: se devuelve el objeto completo (`is_vpn`, `is_proxy` y `vpn_provider` cuando esté presente). No se admiten claves anidadas como `is_vpn` por sí solas.
</ParamField>

### Parámetros de respuesta

La respuesta de la API se devuelve en un [formato JSON](https://www.json.org/json-en.html) universal y ligero.

<ResponseField name="ip_address" type="String">
  La dirección IP enviada para geolocalización.
</ResponseField>

<ResponseField name="city" type="String">
  Nombre de la ciudad.
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  ID de geoname de la ciudad.
</ResponseField>

<ResponseField name="region" type="String">
  Estado o provincia en el que se encuentra la ciudad.
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  Código ISO 3166-2 del estado o provincia.
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  ID de geoname del estado o provincia.
</ResponseField>

<ResponseField name="postal_code" type="String">
  Código postal.
</ResponseField>

<ResponseField name="country" type="String">
  Nombre del país.
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  Código ISO 3166-1 alpha-2 del país.
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  ID de geoname del país.
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  Verdadero si el país está en la UE, falso si no lo está.
</ResponseField>

<ResponseField name="continent" type="String">
  Nombre del continente.
</ResponseField>

<ResponseField name="continent_code" type="Char[2]">
  Código de continente de 2 letras: AF, AS, EU, NA, OC, SA, AN.
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  ID de geoname del continente.
</ResponseField>

<ResponseField name="longitude" type="Float">
  Decimal de la longitud.
</ResponseField>

<ResponseField name="latitude" type="Float">
  Decimal de la latitud.
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  `true` cuando la IP coincide con la base de datos enumerada de nodos de salida VPN (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  `true` cuando la IP coincide con la base de datos de proxy (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  Nombre del servicio VPN de la MMDB (por ejemplo, `NordVPN`). Se omite cuando `is_vpn` es `false`.
</ResponseField>

<ResponseField name="timezone.name" type="String">
  Nombre de la zona horaria de la base de datos IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  Abreviatura de la zona horaria, también de la base de datos IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  Desplazamiento de la zona horaria respecto al horario del meridiano de Greenwich (GMT).
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  Hora actual en la zona horaria local.
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  Verdadero si la ubicación está actualmente en horario de verano (DST).
</ResponseField>

<ResponseField name="flag.svg" type="String">
  Enlace a una versión alojada de la bandera del país en formato SVG.
</ResponseField>

<ResponseField name="flag.png" type="String">
  Enlace a una versión alojada de la bandera del país en formato PNG.
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  Bandera del país como emoji.
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  Bandera del país en unicode.
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  Nombre de la moneda.
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  Código de la moneda en formato ISO 4217.
</ResponseField>

<ResponseField name="connection.connection_type" type="String">
  Inferido del nombre de la organización ASN (por ejemplo, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN y proxy se informan en `security`, no aquí.
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  Número de sistema autónomo.
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  Nombre de la organización del sistema autónomo.
</ResponseField>

<ResponseField name="connection.isp_name" type="String">
  Nombre del proveedor de servicios de Internet (ISP).
</ResponseField>

<ResponseField name="connection.organization_name" type="String">
  Nombre de la organización.
</ResponseField>

### Limitar campos de respuesta

Puede elegir recibir solo algunos campos de la respuesta JSON. Para ello, puede incluir un valor fields en los parámetros de consulta con una lista separada por comas de las claves de nivel superior que desea que se devuelvan.

Por ejemplo, una solicitud para obtener solo el país y la ciudad de una IP tendrá este aspecto:

```
https://ipgeolocation.cleariflow.com/v1/
    ? api_key = YOUR_API_KEY
    & ip_address = 94.198.41.122
    & fields = country,city
```

La respuesta tendría este aspecto:

```json theme={"system"}
{
    "city": "Vienna",
    "country": "Austria"
}
```

## Casos de uso

### Geolocalizar a un visitante del sitio web

Para solicitar la geolocalización de una dirección IP, simplemente incluya su clave API única en la plantilla siguiente.

Tenga en cuenta que no necesita conocer la IP del visitante para realizar la solicitud.

```javascript theme={"system"}
$.getJSON("https://ipgeolocation.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) {
   console.log(data.ip_address);
   console.log(data.country);
})
```

¡Eso es todo lo que necesita para obtener la geolocalización y otros datos de un visitante! Solo hay un parámetro obligatorio: su clave API única.

## Códigos de respuesta y error

Siempre que realice una solicitud que falle por algún motivo, también se devuelve un error en formato JSON. Los errores incluyen un código y una descripción, que puede encontrar en detalle a continuación.

| Code | Type                  | Details                                                                                                                                                                            |
| ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Todo funcionó como se esperaba.                                                                                                                                                    |
| 204  | OK                    | No hay datos de ubicación para la IP enviada.                                                                                                                                      |
| 400  | Bad request           | Solicitud incorrecta.                                                                                                                                                              |
| 401  | Unauthorized          | La solicitud no fue aceptable. Normalmente debido a que la clave API falta o es incorrecta.                                                                                        |
| 422  | Quota reached         | La solicitud se abortó por créditos API insuficientes. (Planes gratuitos)                                                                                                          |
| 429  | Too many requests     | La solicitud se abortó porque se alcanzó el número de solicitudes permitidas por segundo. Esto ocurre en planes gratuitos, ya que las solicitudes están limitadas a 1 por segundo. |
| 500  | Internal server error | La solicitud no pudo completarse debido a un error en el servidor.                                                                                                                 |
| 503  | Service unavailable   | El servidor no estaba disponible.                                                                                                                                                  |

## Códigos de país

A continuación se muestra una lista de códigos de país ISO 3166 Alpha 2 de dos letras que se utilizan en la respuesta. Vea esta lista en un [CSV](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing).

| Nombre del país                 | Código del país |
| ------------------------------- | --------------- |
| Afganistán                      | AF              |
| Albania                         | AL              |
| Argelia                         | DZ              |
| Samoa Americana                 | AS              |
| Andorra                         | AD              |
| Angola                          | AO              |
| Anguila                         | AI              |
| Antigua y Barbuda               | AG              |
| Argentina                       | AR              |
| Armenia                         | AM              |
| Aruba                           | AW              |
| Australia                       | AU              |
| Austria                         | AT              |
| Azerbaiyán                      | AZ              |
| Baréin                          | BH              |
| Bangladesh                      | BD              |
| Barbados                        | BB              |
| Bielorrusia                     | BY              |
| Bélgica                         | BE              |
| Belice                          | BZ              |
| Benín                           | BJ              |
| Bermudas                        | BM              |
| Bután                           | BT              |
| Bolivia                         | BO              |
| Bosnia y Herzegovina            | BA              |
| Botsuana                        | BW              |
| Brasil                          | BR              |
| Islas Vírgenes Británicas       | VG              |
| Brunéi                          | BN              |
| Bulgaria                        | BG              |
| Burkina Faso                    | BF              |
| Burundi                         | BI              |
| Cabo Verde                      | CV              |
| Camboya                         | KH              |
| Camerún                         | CM              |
| Canadá                          | CA              |
| Islas Caimán                    | KY              |
| República Centroafricana        | CF              |
| Chad                            | TD              |
| Chile                           | CL              |
| China                           | CN              |
| Colombia                        | CO              |
| Comoras                         | KM              |
| Congo                           | CG              |
| República Democrática del Congo | CD              |
| Islas Cook                      | CK              |
| Costa Rica                      | CR              |
| Costa de Marfil                 | CI              |
| Croacia                         | HR              |
| Cuba                            | CU              |
| Curazao                         | CW              |
| Chipre                          | CY              |
| Chequia                         | CZ              |
| Dinamarca                       | DK              |
| Yibuti                          | DJ              |
| Dominica                        | DM              |
| República Dominicana            | DO              |
| Timor Oriental                  | TL              |
| Ecuador                         | EC              |
| Egipto                          | EG              |
| El Salvador                     | SV              |
| Guinea Ecuatorial               | GQ              |
| Eritrea                         | ER              |
| Estonia                         | EE              |
| Esuatini                        | SZ              |
| Etiopía                         | ET              |
| Islas Malvinas                  | FK              |
| Islas Feroe                     | FO              |
| Fiyi                            | FJ              |
| Finlandia                       | FI              |
| Francia                         | FR              |
| Guayana Francesa                | GF              |
| Polinesia Francesa              | PF              |
| Gabón                           | GA              |
| Gambia                          | GM              |
| Georgia                         | GE              |
| Alemania                        | DE              |
| Ghana                           | GH              |
| Gibraltar                       | GI              |
| Grecia                          | GR              |
| Groenlandia                     | GL              |
| Granada                         | GD              |
| Guadalupe                       | GP              |
| Guam                            | GU              |
| Guatemala                       | GT              |
| Guernsey                        | GG              |
| Guinea                          | GN              |
| Guinea-Bisáu                    | GW              |
| Guyana                          | GY              |
| Haití                           | HT              |
| Honduras                        | HN              |
| Hong Kong                       | HK              |
| Hungría                         | HU              |
| Islandia                        | IS              |
| India                           | IN              |
| Indonesia                       | ID              |
| Irán                            | IR              |
| Irak                            | IQ              |
| Irlanda                         | IE              |
| Isla de Man                     | IM              |
| Israel                          | IL              |
| Italia                          | IT              |
| Jamaica                         | JM              |
| Japón                           | JP              |
| Jersey                          | JE              |
| Jordania                        | JO              |
| Kazajistán                      | KZ              |
| Kenia                           | KE              |
| Kiribati                        | KI              |
| Kosovo                          | XK              |
| Kuwait                          | KW              |
| Kirguistán                      | KG              |
| Laos                            | LA              |
| Letonia                         | LV              |
| Líbano                          | LB              |
| Lesoto                          | LS              |
| Liberia                         | LR              |
| Libia                           | LY              |
| Liechtenstein                   | LI              |
| Lituania                        | LT              |
| Luxemburgo                      | LU              |
| Macao                           | MO              |
| Madagascar                      | MG              |
| Malaui                          | MW              |
| Malasia                         | MY              |
| Maldivas                        | MV              |
| Malí                            | ML              |
| Malta                           | MT              |
| Islas Marshall                  | MH              |
| Martinica                       | MQ              |
| Mauritania                      | MR              |
| Mauricio                        | MU              |
| Mayotte                         | YT              |
| México                          | MX              |
| Micronesia                      | FM              |
| Moldavia                        | MD              |
| Mónaco                          | MC              |
| Mongolia                        | MN              |
| Montenegro                      | ME              |
| Montserrat                      | MS              |
| Marruecos                       | MA              |
| Mozambique                      | MZ              |
| Myanmar                         | MM              |
| Namibia                         | NA              |
| Nauru                           | NR              |
| Nepal                           | NP              |
| Países Bajos                    | NL              |
| Nueva Caledonia                 | NC              |
| Nueva Zelanda                   | NZ              |
| Nicaragua                       | NI              |
| Níger                           | NE              |
| Nigeria                         | NG              |
| Corea del Norte                 | KP              |
| Macedonia del Norte             | MK              |
| Islas Marianas del Norte        | MP              |
| Noruega                         | NO              |
| Omán                            | OM              |
| Pakistán                        | PK              |
| Palaos                          | PW              |
| Panamá                          | PA              |
| Papúa Nueva Guinea              | PG              |
| Paraguay                        | PY              |
| Perú                            | PE              |
| Filipinas                       | PH              |
| Polonia                         | PL              |
| Portugal                        | PT              |
| Puerto Rico                     | PR              |
| Catar                           | QA              |
| Reunión                         | RE              |
| Rumanía                         | RO              |
| Rusia                           | RU              |
| Ruanda                          | RW              |
| Santa Elena                     | SH              |
| San Cristóbal y Nieves          | KN              |
| Santa Lucía                     | LC              |
| San Martín                      | MF              |
| San Pedro y Miquelón            | PM              |
| San Vicente y las Granadinas    | VC              |
| Samoa                           | WS              |
| San Marino                      | SM              |
| Santo Tomé y Príncipe           | ST              |
| Arabia Saudita                  | SA              |
| Senegal                         | SN              |
| Serbia                          | RS              |
| Seychelles                      | SC              |
| Sierra Leona                    | SL              |
| Singapur                        | SG              |
| Sint Maarten                    | SX              |
| Eslovaquia                      | SK              |
| Eslovenia                       | SI              |
| Islas Salomón                   | SB              |
| Somalia                         | SO              |
| Sudáfrica                       | ZA              |
| Corea del Sur                   | KR              |
| Sudán del Sur                   | SS              |
| España                          | ES              |
| Sri Lanka                       | LK              |
| San Bartolomé                   | BL              |
| Sudán                           | SD              |
| Surinam                         | SR              |
| Suecia                          | SE              |
| Suiza                           | CH              |
| Siria                           | SY              |
| Taiwán                          | TW              |
| Tayikistán                      | TJ              |
| Tanzania                        | TZ              |
| Tailandia                       | TH              |
| Bahamas                         | BS              |
| Togo                            | TG              |
| Tonga                           | TO              |
| Trinidad y Tobago               | TT              |
| Túnez                           | TN              |
| Turquía                         | TR              |
| Turkmenistán                    | TM              |
| Islas Turcas y Caicos           | TC              |
| Tuvalu                          | TV              |
| Uganda                          | UG              |
| Ucrania                         | UA              |
| Emiratos Árabes Unidos          | AE              |
| Reino Unido                     | GB              |
| Estados Unidos                  | US              |
| Uruguay                         | UY              |
| Islas Vírgenes de EE. UU.       | VI              |
| Uzbekistán                      | UZ              |
| Vanuatu                         | VU              |
| Ciudad del Vaticano             | VA              |
| Venezuela                       | VE              |
| Vietnam                         | VN              |
| Wallis y Futuna                 | WF              |
| Yemen                           | YE              |
| Zambia                          | ZM              |
| Zimbabue                        | ZW              |

## Otras notas

Información importante de facturación: cada dirección IP que procese consume un crédito. La facturación se realiza por solicitud enviada, independientemente de si la respuesta es exitosa. Por lo tanto, incluso enviar una dirección IP no válida como "fda3346ds" seguirá descontando un crédito de su cuenta.