Locations v1 / GeoIP

GeoIP — un IP anume

Ca varianta fără parametru, dar pentru un IP dat în cale (/geoip/{ip}). Util pentru
a verifica orice adresă IP, nu doar a apelantului.

GET

https://oneapi.ro/api/locations/v1/geoip/{ip}

Parametri de cale

NumeTipDescriereExemplu

ipobligatoriu string Adresa IP căutată, IPv4 sau IPv6.

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

Ca /geoip, dar pentru un IP dat în cale — verifică orice adresă IP, nu doar a apelantului.
IP în RO → regiune/județ/UAT/localitate din datele noastre; în afara RO / privat → in_romania: false; IP invalid → 422.

La ce folosește

Îmbogățirea log-urilor sau lead-urilor cu județul aproximativ al unui IP colectat.
Verificarea geografică a unui IP dintr-un webhook/comandă înainte de rutare regională.
Filtrare server-side pe un IP dat în cale, nu doar al apelantului.

Structura răspunsului

CâmpTipDescriere

data.ip string IP-ul cerut.

data.in_romania boolean Dacă IP-ul cade în interiorul granițelor RO. false → niciun alt câmp.

data.regiune[] mixed Regiunea în care cade IP-ul; apare doar când precizia a permis rezolvarea administrativă.opțional

data.judet[] mixed Județul în care cade IP-ul; apare doar când precizia a permis rezolvarea.opțional

data.uat[] mixed UAT-ul în care cade IP-ul; apare doar când precizia a permis rezolvarea.opțional

data.localitate[] object[] Localitatea în care cade IP-ul; poate fi null chiar și când județul e cunoscut.opțional

data.localitate.distanta_m integer Distanța de la punctul IP la localitatea returnată (metri).

meta.distanta object Cum sunt măsurate distanţele din răspuns. Apare pe orice răspuns care conţine o distanţă.

meta.distanta.metoda string Mereu linie_dreapta: distanţa geodezică pe suprafaţa Pământului, nu pe drum.

meta.distanta.detaliu string Aceeaşi informaţie, în cuvinte.

Exemple de răspuns

Rezolvat în Cluj-Napoca + județ/UAT/localitate.

GEThttps://oneapi.ro/api/locations/v1/geoip/188.27.0.1

{
    "data": {
        "ip": "188.27.0.1",
        "in_romania": true,
        "regiune": {
            "cod": "RO11",
            "nume": "Nord-Vest"
        },
        "judet": {
            "cod": "CJ",
            "nume": "Cluj"
        },
        "uat": {
            "cod_siruta": 54975,
            "nume": "Cluj-Napoca",
            "tip": "municipiu"
        },
        "localitate": {
            "cod_siruta": 54984,
            "nume": "Cluj-Napoca",
            "tip": "resedinta_municipiu",
            "distanta_m": 3120
        }
    },
    "meta": {
        "sursa": "MaxMind GeoLite2",
        "precizie": "aproximativa",
        "atribuire": "This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.",
        "distanta": {
            "metoda": "linie_dreapta",
            "detaliu": "Distanţele sunt geodezice, în linie dreaptă pe suprafaţa Pământului (WGS84) — nu pe drum."
        }
    }
}

În afara RO → in_romania false.

GEThttps://oneapi.ro/api/locations/v1/geoip/8.8.8.8

{
    "data": {
        "ip": "8.8.8.8",
        "in_romania": false
    },
    "meta": {
        "sursa": "MaxMind GeoLite2",
        "precizie": "necunoscuta",
        "atribuire": "This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com."
    }
}

Nerezolvabil → in_romania false.

GEThttps://oneapi.ro/api/locations/v1/geoip/127.0.0.1

{
    "data": {
        "ip": "127.0.0.1",
        "in_romania": false
    },
    "meta": {
        "sursa": "MaxMind GeoLite2",
        "precizie": "necunoscuta",
        "atribuire": "This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com."
    }
}

Coduri de eroare

Cod	Slug	Când apare
401	neautentificat	Token lipsă, invalid, expirat sau revocat.
403	feature_indisponibil	Planul curent nu include funcţia de care ţine ruta.
404	negasit	Nu există nimic pentru `ip` din cale.
422	ip_invalid	Adresa IP din cale nu e validă.
429	cota_depasita	Cota lunară a planului a fost depăşită (vezi `Retry-After`).

Toate erorile au aceeași formă. eroare.cod e stabil și e cel după care trebuie să ramifici în cod — nu după textul din mesaj, care se poate schimba.

{
    "eroare": {
        "cod": "ip_invalid",
        "mesaj": "Adresa IP din cale nu e validă.",
        "detalii": {
            "ip": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}