Locations v1 / Geo & reverse

Geocoding

Address → coordinates plus precision (numar if the house number is mapped, otherwise strada). Two variants: a free string (?adresa=Strada Magnoliei 2, Cluj-Napoca) or structured (?localitate={cod_siruta}&strada=&numar=). Unresolvable → data null.

GET

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

Query parameters

NameTypeDescriptionAccepted values

adresaoptional string | null The address as free text (an alternative to the structured fields). max 250 car.

localitateoptional integer | null The locality's cod_siruta (structured variant). e.g. 54984

stradaoptional string | null The street name (it gets normalised). max 200 car.

numaroptional string | null The house number (optional). max 20 car.

How it behaves

Two variants: free string (?adresa=Strada Magnoliei 2, Cluj-Napoca) or structured (?localitate={cod_siruta}&strada=&numar=).
With a free string: the locality is the last comma-separated segment, the type prefix (Strada/Bd./Calea) is ignored, and a trailing number is detected.
precizie = numar when the number is mapped in OSM, otherwise strada (the street's centre). Unresolvable → data null.

What it is for

Turning addresses from a CRM or order system into coordinates for map display.
Automatically placing a pin when an order is created from a typed address.
Bulk geocoding a customer database for territorial analysis.

Response structure

FieldTypeDescription

data.lat number Latitude (WGS 84).

data.lng number Longitude (WGS 84).

data.precizie string numar | strada.

data.strada.id integer The internal id of the street found.

data.strada.nume string The name of the street found.

data.numar string | null The house number identified, where one was given.

data.cod_postal string | null The postal code.

data.localitate object Present when geocoding from a free string.

data.localitate.cod_siruta integer The locality's SIRUTA code — chainable to /localitati/{cod}.

data.localitate.nume string The name of the locality.

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

Response examples

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"
    }
}

Error codes

Code	Slug	When it occurs
401	neautentificat	Token missing, invalid, expired or revoked.
403	feature_indisponibil	The current plan does not include the feature the route depends on.
422	parametri_invalizi	`adresa` or (`localitate`+`strada`) is missing.
429	cota_depasita	The plan's monthly quota has been exceeded (see `Retry-After`).

All errors share the same shape. eroare.cod is stable and is the value you should branch on in code — not the text in mesaj, which may change.

{
    "eroare": {
        "cod": "parametri_invalizi",
        "mesaj": "adresa or (localitate+strada) is missing.",
        "detalii": {
            "adresa": [
                "The value sent does not satisfy the parameter rule."
            ]
        }
    }
}