oneapi
Autentificare
Locations v1 / Proximitate & zone

Localități pe rază

Localitățile active dintr-o rază (km) în jurul unui centru — un punct (lat/lng) sau
o localitate (de=cod_siruta, exclusă din rezultat). Ordonate după distanță, paginate.
Cu ?include=secundare întoarce și cătunele/cartierele din rază (listă nepaginată, în meta.secundare).

GET
https://oneapi.ro/api/locations/v1/aproape

Parametri de interogare

NumeTipDescriereValori acceptate
latopțional number | null Latitudinea centrului (sau folosește de). -90 – 90
lngopțional number | null Longitudinea centrului. -180 – 180
deopțional integer | null cod_siruta al localității-centru (alternativă la lat/lng). ex. 54984
raza_kmobligatoriu number Raza în km. 0.1 – 100
includelistăopțional text secundare = cătune/cartiere din rază (listă nepaginată, în meta.secundare). secundare

Cum se comportă

  • Centru = un punct (lat/lng) sau o localitate (de=cod_siruta, exclusă din rezultat).
  • Ordonate după distanță; distanta_m = distanța geodezică până la centru.

La ce folosește

  • Determinarea orașelor/comunelor din raza de livrare a unui depozit sau magazin.
  • Sugestii „localități din apropiere" când clientul își alege zona.
  • Construirea zonei de captare (catchment) în jurul unui punct de vânzare.

Structura răspunsului

CâmpTipDescriere
data[].cod_siruta integer Codul SIRUTA (cheia publică a entității).
data[].nume string Denumirea entității.
data[].tip string Tipul entității (cod brut; denumirile la /nomenclatoare/tipuri).
data[].judet.cod string Indicativul auto al județului.
data[].judet.nume string Numele județului.
data[].lat number Latitudine (WGS84).
data[].lng number Longitudine (WGS84).
data[].distanta_m integer Distanța, în metri.
meta.paginare.pagina integer Pagina curentă.
meta.paginare.per_pagina integer Rezultate pe pagină.
meta.paginare.total integer Total rezultate.
meta.paginare.pagini integer Număr de pagini.
meta.actualizat object Prospețimea datelor pe domenii (dată ISO 8601).
meta.secundare array Cătune/cartiere din rază (nepaginat, separat de pagina din data) — doar cu include=secundare.
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

GEThttps://oneapi.ro/api/locations/v1/aproape?lat=46.77&lng=23.59&raza_km=10
{
    "data": [
        {
            "cod_siruta": 54984,
            "nume": "Cluj-Napoca",
            "tip": "resedinta_municipiu",
            "judet": {
                "cod": "CJ",
                "nume": "Cluj"
            },
            "lat": 46.78,
            "lng": 23.559444444444,
            "distanta_m": 2585
        }
    ],
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "geo": "2026-09-04T21: 24: 20+03: 00"
        },
        "paginare": {
            "pagina": 1,
            "per_pagina": 20,
            "total": 12,
            "pagini": 1
        },
        "distanta": {
            "metoda": "linie_dreapta",
            "detaliu": "Distanţele sunt geodezice, în linie dreaptă pe suprafaţa Pământului (WGS84) — nu pe drum."
        }
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
404negasitResursa cerută nu există.
422parametri_invalizilipsă centru sau raza_km.
429cota_depasitaCota 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": "parametri_invalizi",
        "mesaj": "lipsă centru sau raza_km.",
        "detalii": {
            "lat": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}