API-Dokumentation

Ihre erste API-Anfrage

curl --get 'https://www.geoipy.com/api/IPsInfo' \
  --data-urlencode 'ip=8.8.8.8' \
  --header 'X-API-Key: YOUR_API_KEY'

HTTPS und X-API-Key verwenden. Schlüssel in URLs können protokolliert werden. Unterschiedliche Header-/URL-Schlüssel ergeben HTTP 400.

Schlüssel im Dashboard erstellen. Vollständiger Wert nur einmal sichtbar. Privat auf dem Server speichern, nie im Browsercode oder öffentlichen Repository. Ein Ersatz macht den alten Schlüssel sofort ungültig. Widerruf oder Ablauf stoppt neue Anfragen; angenommene können enden.

Antwort und Aktualität

HTTP 200 liefert JSON. Verkürztes Beispiel; verfügbare Felder hängen vom Anbieter ab.

{
  "ip": "8.8.8.8",
  "type": "ipv4",
  "country_code": "US"
}

Cache-Frische standardmäßig 12 Stunden. X-Data-Fetched-At nennt die UTC-Abrufzeit. Bei Aktualisierungsfehlern keine abgelaufenen Daten; Abrufzeit ist nicht Datenalter.

X-Request-ID identifiziert die Anfrage für den Support. Geolokalisierung ist ein ungefährer Netzwerkstandort, nicht der exakte Standort einer Person.

Nutzung und Wiederholungen

Erfolgreiche Anfragen einschließlich Cache zählen zum Kontingent. Laufende reservieren Kapazität, Fehler geben sie frei. Rücksetzung am Monatsersten um 00:00 UTC. Tarif- oder Schlüsselwechsel setzt die Nutzung nicht zurück.

Bei HTTP 429 oder temporären 503/504 Retry-After beachten und begrenzt mit steigenden Abständen wiederholen. Ungültige Eingaben oder Zugangsdaten zuerst korrigieren.

Fehler

Fehler liefern application/json mit HTTP-Fehlerstatus. API-Bezeichner und Beispielinhalte behalten ihre dokumentierte Form.

{
  "success": false,
  "error": {
    "code": 104,
    "type": "usage_limit_reached",
    "info": "The monthly API allowance has been reached."
  }
}

Serverseitige Beispiele

JavaScript · Server

const url = new URL('https://www.geoipy.com/api/IPsInfo');
url.searchParams.set('ip', '8.8.8.8');
const response = await fetch(url, {
  headers: { 'X-API-Key': process.env.GEOIPY_API_KEY }
});
const data = await response.json();
if (!response.ok) throw new Error(data.error.info);
console.log(data);

C#

using (var client = new System.Net.Http.HttpClient())
{
    client.DefaultRequestHeaders.Add("X-API-Key",
        System.Environment.GetEnvironmentVariable("GEOIPY_API_KEY"));
    var response = await client.GetAsync(
        "https://www.geoipy.com/api/IPsInfo?ip=8.8.8.8");
    var json = await response.Content.ReadAsStringAsync();
    // Inspect response.StatusCode and parse json before retrying.
}

Python

import os, requests
response = requests.get(
    'https://www.geoipy.com/api/IPsInfo',
    params={'ip': '8.8.8.8'},
    headers={'X-API-Key': os.environ['GEOIPY_API_KEY']},
    timeout=15)
data = response.json()
response.raise_for_status()

PHP

$url = 'https://www.geoipy.com/api/IPsInfo?' . http_build_query(['ip' => '8.8.8.8']);
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('GEOIPY_API_KEY')]]);
$json = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($json === false) { throw new RuntimeException('The request failed.'); }
curl_close($ch);
$data = json_decode($json, true);
// Inspect $status and $data['error'] when the status is not 200.