Locations v1 / Geo & reverse

Geocodare

Adresă → coordonată + precizie (numar dacă numărul e mapat, altfel strada). Două
variante: string liber (?adresa=Strada Magnoliei 2, Cluj-Napoca) sau structurat
(?localitate={cod_siruta}&strada=&numar=). Nerezolvabil → data null.

GET

https://oneapi.ro/api/locations/v1/geocodare

Parametri de interogare

NumeTipDescriereValori acceptate

adresaopțional string | null Adresă ca text liber (alternativă la câmpurile structurate). max 250 car.

localitateopțional integer | null cod_siruta al localității (variantă structurată). ex. 54984

stradaopțional string | null Numele străzii (se normalizează). max 200 car.

numaropțional string | null Numărul poștal (opțional). max 20 car.

Cum se comportă

Două variante: string liber (?adresa=Strada Magnoliei 2, Cluj-Napoca) sau structurat (?localitate={cod_siruta}&strada=&numar=).
La string liber: localitatea = ultimul segment după virgulă, prefixul de tip (Strada/Bd./Calea) e ignorat, numărul de la final e detectat.
precizie = numar când numărul e mapat în OSM, altfel strada (centrul străzii). Nerezolvabil → data null.

La ce folosește

Transformarea adreselor din CRM/comenzi în coordonate pentru afișare pe hartă.
Plasarea automată a unui pin la crearea comenzii dintr-o adresă tastată.
Geocodarea în masă a bazei de clienți pentru analize teritoriale.

Structura răspunsului

CâmpTipDescriere

data.lat number Latitudine (WGS84).

data.lng number Longitudine (WGS84).

data.precizie string numar | strada.

data.strada.id integer Id-ul intern al străzii găsite.

data.strada.nume string Denumirea străzii găsite.

data.numar string | null Numărul poștal identificat, unde a fost dat.

data.cod_postal string | null Codul poștal.

data.localitate object Prezentă la geocodarea din string liber.

data.localitate.cod_siruta integer Codul SIRUTA al localității — chainable spre /localitati/{cod}.

data.localitate.nume string Denumirea localității.

meta.actualizat object Prospețimea datelor pe domenii (dată ISO 8601).

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/geocodare?adresa=Strada%20Magnoliei%202,%20Cluj-Napoca

{
    "data": {
        "lat": 46.75725404999999,
        "lng": 23.5865691,
        "precizie": "numar",
        "strada": {
            "id": 16416,
            "nume": "Magnoliei"
        },
        "numar": "2",
        "cod_postal": "400487",
        "localitate": {
            "cod_siruta": 54984,
            "nume": "Cluj-Napoca"
        }
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "geo": "2026-09-04T21: 24: 20+03: 00"
        },
        "atribuire": "© OpenStreetMap contributors"
    }
}

GEThttps://oneapi.ro/api/locations/v1/geocodare?localitate=54984&strada=Magnoliei&numar=2

{
    "data": {
        "lat": 46.75725404999999,
        "lng": 23.5865691,
        "precizie": "numar",
        "strada": {
            "id": 16416,
            "nume": "Magnoliei"
        },
        "numar": "2",
        "cod_postal": "400487"
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "geo": "2026-09-04T21: 24: 20+03: 00"
        },
        "atribuire": "© OpenStreetMap contributors"
    }
}

GEThttps://oneapi.ro/api/locations/v1/geocodare?localitate=54984&strada=Magnoliei

{
    "data": {
        "lat": 46.75741898636447,
        "lng": 23.586320615822498,
        "precizie": "strada",
        "strada": {
            "id": 16416,
            "nume": "Magnoliei"
        },
        "numar": null,
        "cod_postal": null
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "geo": "2026-09-04T21: 24: 20+03: 00"
        },
        "atribuire": "© OpenStreetMap contributors"
    }
}

GEThttps://oneapi.ro/api/locations/v1/geocodare?adresa=Str.%20Memorandumului%2028%2C%20Cluj-Napoca

{
    "data": {
        "lat": 46.769304853413416,
        "lng": 23.585544611959204,
        "precizie": "numar",
        "strada": {
            "id": 14540,
            "nume": "Memorandumului"
        },
        "numar": "28",
        "cod_postal": "400114",
        "localitate": {
            "cod_siruta": 54984,
            "nume": "Cluj-Napoca"
        }
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "geo": "2026-09-04T21: 24: 20+03: 00"
        },
        "atribuire": "© OpenStreetMap contributors"
    }
}

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.
422	parametri_invalizi	`adresa` sau (`localitate`+`strada`) lipsă.
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": "parametri_invalizi",
        "mesaj": "adresa sau (localitate+strada) lipsă.",
        "detalii": {
            "adresa": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}