oneapi
Sign in
Locations v1 / Căutare & rezolvare

Entity by external identifier

⭐ Translates an identifier from another dataset into our entity: wikidata (QID), geonames (numeric id) or nuts (a NUTS-2 or NUTS-3 code). The other direction — an entity's external identifiers — is in the response of the detail routes.

GET
https://oneapi.ro/api/locations/v1/referinte/{sursa}/{id}

Path parameters

NameTypeDescriptionExample
sursarequired string Source of the external identifier (wikidata, geonames, osm).
idrequired string Identifier in the chosen external source (e.g. Q182624 at Wikidata).

Query parameters

This route accepts no query parameters.

How it behaves

  • ⭐ The bridge in reverse: an entity's external identifiers appear in the detail routes' responses, and here you start from them and come back to the entity.
  • Accepted sources: wikidata (QID, e.g. Q182624), geonames (numeric id) and nuts (a NUTS-2 or NUTS-3 code).
  • The response is a list, not a single object, because the same external identifier can describe more than one of our levels: GeoNames has a single entry for „Cluj-Napoca" (681290), which for us is both an administrative unit and a locality. That is not a duplicate — they are two distinct entities.
  • NUTS covers two levels: NUTS-2 are the development regions (their code is the NUTS code), NUTS-3 are the counties. Below county level there is no NUTS.
  • Matching is case-insensitive (q182624 = Q182624).

What it is for

  • You have a dataset keyed on Wikidata or GeoNames and want to join it with ours without matching on names.
  • Translating a NUTS code from a Eurostat table into the corresponding county or region.
  • Checking that an external identifier really does correspond to the entity you think it does.

Response structure

FieldTypeDescription
data[].nivel string The level of the entity found: regiune, judet, uat or localitate.
data[].cod string The public key of that level — the registration prefix for a county, the NUTS code for a region, the SIRUTA code for an administrative unit or locality.
data[].nume string The canonical name.
data[].tip string | null The entity type, where one exists (comuna/oras/sat…).
data[].parinte.nivel string The level of the parent entity.
data[].parinte.cod string The public key of the parent entity.
data[].parinte.nume string The name of the parent entity.
data[].parinte.judet string The county's registration prefix — present only when the entity found is a locality.opțional
meta.actualizat object Prospețimea datelor pe domenii (dată ISO 8601).

Response examples

GEThttps://oneapi.ro/api/locations/v1/referinte/wikidata/Q182624
{
    "data": [
        {
            "nivel": "judet",
            "cod": "CJ",
            "nume": "Cluj",
            "tip": null,
            "parinte": null
        }
    ],
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "referinte_externe": "2026-09-04T21: 24: 20+03: 00"
        }
    }
}

Error codes

CodeSlugWhen it occurs
401neautentificatToken missing, invalid, expired or revoked.
403feature_indisponibilThe current plan does not include the feature the route depends on.
404negasitUnknown source (the response lists the accepted ones), or no result for that identifier.
429cota_depasitaThe 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": "negasit",
        "mesaj": "Unknown source (the response lists the accepted ones), or no result for that identifier."
    }
}