Date de referințăNou

API Localități cu SIRUTA și cod poștal

Nomenclatorul geografic al Ministerului Finanțelor: fiecare localitate cu codul SIRUTA, SIRUTA părintelui (comuna/orașul), tipul, codul poștal, dacă are primărie și CUI-ul primăriei. Codurile loc_jud_cod și loc_cod leagă localitatea de străzile ei.

GET/api/v1/nomenclator/localitate/{siruta}
1 credit fix· credite generale
Obține cheie API gratuită Documentație Prețuri →
după cheie + căutare cu filtre
2 endpoint-uridupă cheie + căutare cu filtre
la căutarea după cheie
1 credit fixla căutarea după cheie
explicate mai jos
11 câmpuriexplicate mai jos
GET/api/v1/nomenclator/localitate/54975
X-API-KEY: CHEIA_TA_API
{
  "success": true,
  "siruta": "54975",
  "sursa": "Ministerul Finanțelor — nomenclatorul geografic",
  "rezultat": {
    "siruta": 54975,
    "siruta_tata": null,
    "denumire": "Cluj-Napoca",
    "tip": "Mun",
    "judet_cod": 12,
    "loc_jud_cod": 12,
    "loc_cod": 512,
    "cod_postal": null,
    "are_primarie": true,
    "cui_primarie": null,
    "loc_cod_artere": 103
  }
}
200 OKSursă: Ministerul Finanțelor — nomenclatorul geografic
Toate câmpurile →

Exemplu cu date fictive · bază URL https://www.firmeapi.ro/api/v1

Despre date

Localități cu SIRUTA și cod poștal

Localitățile României cu SIRUTA, cod poștal, comuna-mamă și CUI-ul primăriei.

Nomenclatorul geografic al Ministerului Finanțelor: fiecare localitate cu codul SIRUTA, SIRUTA părintelui (comuna/orașul), tipul, codul poștal, dacă are primărie și CUI-ul primăriei. Codurile loc_jud_cod și loc_cod leagă localitatea de străzile ei.

Sursa
Ministerul Finanțelor — nomenclatorul geografic
Credite
Generale — incluse în orice abonament

Integrare cu agenți AI

Agentul tău îl integrează din prima

Un ghid complet, scris pentru agenții de programare: endpoint-uri, câmpuri, erori, cod de referință și teste de acceptanță. Agentul face integrarea cap-coadă, fără să te întrebe nimic. Sau îl conectezi prin MCP și interoghează direct datele.

Ghidul pentru agenți
.md →
Specificația OpenAPI
openapi.json →
Rezumat pentru LLM-uri
llms.txt →
Ghid MCP pe fiecare client
Configurare MCP →

Prompt pentru agentul de programare

Agentul deschide ghidul de la adresa din prompt. Dacă nu poate accesa internetul, copiază-i . 

Implementează în aplicația mea integrarea cu API-ul Localități cu SIRUTA și cod poștal FirmeAPI.ro.

Citește întâi ghidul complet de implementare:
https://www.firmeapi.ro/info-api/localitati-coduri-postale.md

Urmează-l pas cu pas: configurarea cheii FIRMEAPI_KEY, clientul API cu
tratarea erorilor și reîncercările, cache-ul, regulile de domeniu
interfața și testele de acceptanță.

Respectă convențiile proiectului. La final rulează testele și spune-mi ce
fișiere ai creat sau modificat.

Documentație

Referința API

Parametrii, fiecare câmp al răspunsului și răspunsurile pe coduri de stare, cu exemple de cod în patru limbaje.

Bază URL
https://www.firmeapi.ro/api/v1
Autentificare
X-API-KEY: cheia ta
Format
JSON, UTF-8, date YYYY-MM-DD
Erori
nu consumă credite

O localitate după SIRUTA#

GET/api/v1/nomenclator/localitate/{siruta}
1 credit fix· general

Detaliile localității.

Parametri

sirutastring· în URLobligatoriu
Codul SIRUTA al localității. ex.: 54975

Câmpurile răspunsului

successboolean
true când cererea a reușit.
sirutastring
Valoarea cerută, normalizată.
sursastring
Sursa datelor.
rezultatobject
Obiectul găsit.
rezultat.sirutainteger
Codul SIRUTA.
rezultat.siruta_tatainteger|null
SIRUTA părintelui.
rezultat.denumirestring
Denumirea.
rezultat.tipstring
Tipul (Mun, Oraș, Com, Loc, Sat…).
rezultat.judet_codinteger
Codul județului.
rezultat.loc_jud_codinteger
Cheia de legătură cu străzile (județ).
rezultat.loc_codinteger
Codul MFP al localității.
rezultat.loc_cod_artereinteger|null
Pentru orașe: codul rândului care are străzile — folosește-l ca loc_cod la /nomenclator/strazi.
rezultat.cod_postalstring|null
Codul poștal (pentru localitățile cu un singur cod).
rezultat.are_primarieboolean
Dacă are primărie.
rezultat.cui_primarieinteger|null
CUI-ul primăriei.

Reguli pentru integrare

  1. 1Întoarce un singur obiect, în câmpul rezultat.
curl -X GET "https://www.firmeapi.ro/api/v1/nomenclator/localitate/54975" \
  -H "X-API-KEY: CHEIA_TA_API" \
  -H "Accept: application/json"

200 OK · se taxează 1 credit fix

{
  "success": true,
  "siruta": "54975",
  "sursa": "Ministerul Finanțelor — nomenclatorul geografic",
  "rezultat": {
    "siruta": 54975,
    "siruta_tata": null,
    "denumire": "Cluj-Napoca",
    "tip": "Mun",
    "judet_cod": 12,
    "loc_jud_cod": 12,
    "loc_cod": 512,
    "cod_postal": null,
    "are_primarie": true,
    "cui_primarie": null,
    "loc_cod_artere": 103
  }
}

Caută localități#

GET/api/v1/nomenclator/localitati
1 credit / rezultat· general

După denumire, județ, cod poștal sau tip. 1 credit pe rezultat întors.

Parametri

qstring· query
O parte din denumire (cu diacritice, ca în nomenclator). ex.: Cluj
judet_codinteger· query
Codul numeric al județului (1–52).
cod_postalstring· query
Codul poștal.
siruta_tatainteger· query
SIRUTA comunei/orașului părinte.
are_primarieboolean· query
true = doar reședințele cu primărie.
paginainteger· query
Numărul paginii, de la 1. ex.: 1
per_paginainteger· query
Rezultate pe pagină, maxim 100. ex.: 20
ordinestring· query
Ordinea rezultatelor (vezi valorile permise pe endpoint). denumireex.: denumire

Câmpurile răspunsului

successboolean
true când cererea a reușit.
sursastring
Sursa datelor.
pagina · per_paginainteger
Pagina curentă și rezultatele pe pagină.
total · total_paginiinteger
Totalul rezultatelor care se potrivesc filtrelor și numărul de pagini pe care le poți parcurge.
rezultatearray
Rezultatele paginii.
rezultate[].sirutainteger
Codul SIRUTA.
rezultate[].siruta_tatainteger|null
SIRUTA părintelui.
rezultate[].denumirestring
Denumirea.
rezultate[].tipstring
Tipul (Mun, Oraș, Com, Loc, Sat…).
rezultate[].judet_codinteger
Codul județului.
rezultate[].loc_jud_codinteger
Cheia de legătură cu străzile (județ).
rezultate[].loc_codinteger
Codul MFP al localității.
rezultate[].loc_cod_artereinteger|null
Pentru orașe: codul rândului care are străzile — folosește-l ca loc_cod la /nomenclator/strazi.
rezultate[].cod_postalstring|null
Codul poștal (pentru localitățile cu un singur cod).
rezultate[].are_primarieboolean
Dacă are primărie.
rezultate[].cui_primarieinteger|null
CUI-ul primăriei.
cost.credite_consumate · mod · tipinteger · string
Creditele consumate de cerere, modul de taxare (fix sau per_rezultat) și tipul creditelor (general sau premium).

Reguli pentru integrare

  1. 1Maximum 100 rezultate pe pagină. Paginile acoperă toate rezultatele care se potrivesc filtrelor; dacă o căutare e prea largă pentru a fi paginată până la capăt, răspunsul spune până unde poți merge.
  2. 2Costul se calculează pe numărul de rezultate întoarse; o căutare fără rezultate nu costă nimic.
curl -X GET "https://www.firmeapi.ro/api/v1/nomenclator/localitati" \
  -H "X-API-KEY: CHEIA_TA_API" \
  -H "Accept: application/json"

200 OK · se taxează 1 credit / rezultat

{
  "success": true,
  "sursa": "Ministerul Finanțelor — nomenclatorul geografic",
  "pagina": 1,
  "per_pagina": 2,
  "total": 17246,
  "total_pagini": 5000,
  "rezultate": [
    {
      "siruta": 179141,
      "siruta_tata": 179132,
      "denumire": "1",
      "tip": "Sec",
      "judet_cod": 40,
      "loc_jud_cod": 40,
      "loc_cod": 1,
      "cod_postal": null,
      "are_primarie": true,
      "cui_primarie": 4505359
    },
    {
      "siruta": 102552,
      "siruta_tata": 102543,
      "denumire": "1 Decembrie",
      "tip": "Sat",
      "judet_cod": 23,
      "loc_jud_cod": 23,
      "loc_cod": 1,
      "cod_postal": null,
      "are_primarie": false,
      "cui_primarie": null
    }
  ],
  "cost": {
    "credite_consumate": 2,
    "mod": "per_rezultat",
    "tip": "general"
  }
}

Erori și limite

Ce face integrarea la fiecare eroare

Fiecare cod are o reacție clară: unele se reîncearcă automat, restul înseamnă configurare, credite sau date lipsă. Erorile nu consumă credite.

401AUTH_MISSING_KEY · AUTH_INVALID_KEY · AUTH_KEY_EXPIRED

Cheia lipsește, e greșită sau a expirat.

Eroare de configurare: loghează și verifică FIRMEAPI_KEY.

Reîncearcă: nu

403CREDITS_EXHAUSTED

Rezultatele paginii costă mai mult decât creditele disponibile.

Răspunsul spune costul cererii și soldul: cere mai puține rezultate (per_pagina mai mic) sau cumpără credite.

Reîncearcă: nu

403ACCESS_DENIED_IP · ACCESS_DENIED_SCOPE

Cheia e limitată la alte IP-uri sau endpoint-uri.

Eroare de configurare a cheii, din contul FirmeAPI.

Reîncearcă: nu

403MONTHLY_LIMIT_REACHED

Planul gratuit și-a atins limita lunară de cereri.

Mesaj către utilizator cu linkul din upgrade_url.

Reîncearcă: nu

404—

Nu există date pentru cheia cerută.

Afișează „fără date”. Păstrează în cache scurt (de exemplu o oră).

Reîncearcă: nu

422VALIDATION_FAILED

Un filtru invalid sau lipsește un parametru obligatoriu.

Arată eroarea din errors, pe câmp. Validează înainte de cerere.

Reîncearcă: nu

429LIMIT_EXCEEDED_SECOND

Prea multe cereri într-o secundă.

Așteaptă retry_after secunde și reia cererea.

Reîncearcă: da

429LIMIT_EXCEEDED_DAILY · LIMIT_EXCEEDED_MONTHLY

Limita zilnică sau lunară a planului.

Oprește cererile până la retry_after și anunță utilizatorul.

Reîncearcă: nu

500—

Eroare neașteptată pe server.

Reîncearcă de cel mult 3 ori, la 1, 2 și 4 secunde.

Reîncearcă: da

Corpul erorii: {"success": false, "error": "…", "code": "…", "message": "…"}. Decide după statusul HTTP și code, nu după text. Nicio eroare nu consumă credite.

Header-e de răspuns

X-Credit-Cost
Creditele consumate de cerere.
X-Credit-Type
Tipul creditelor folosite de endpoint.
X-Credit-Balance-General
Soldul de credite generale.
X-Credit-Balance-{TIP}
Soldul pentru tipul cererii, când nu e general (de exemplu X-Credit-Balance-ACTIONARI).
X-RateLimit-Limit-Second · -Day · -Month
Limitele planului.
X-RateLimit-Remaining-Second · -Day · -Month
Cât a mai rămas din fiecare limită.

Utilizare

Unde îl folosesc clienții

  • 01

    Completarea automată a adreselor și a codului poștal

  • 02

    Găsirea primăriei unei localități

Date de referință

Din aceeași categorie

Toate seturile de date →

FAQ

Întrebări frecvente

Nu găsești răspunsul? Scrie-ne.

Cât costă API-ul Localități cu SIRUTA și cod poștal?

/api/v1/nomenclator/localitate/{siruta}: 1 credit fix; /api/v1/nomenclator/localitati: 1 credit / rezultat. Căutările cu filtre se taxează pe rezultat: creditele consumate = rezultatele întoarse × prețul endpoint-ului, deci o pagină de 20 costă de zece ori mai puțin decât una de 200. Erorile și răspunsurile fără date (404 sau zero rezultate) nu consumă credite și nu scad din plafonul zilnic.

De unde provin datele?

Ministerul Finanțelor — nomenclatorul geografic.

Ce înseamnă un câmp null?

Că sursa nu precizează informația pentru acel rând. Nu completăm golurile cu valori deduse.

Pot limita o cheie API doar la aceste endpoint-uri?

Da. La Chei API → Acces alegi „Doar ce aleg eu” și bifezi endpoint-urile dorite; restul primesc 403 ACCESS_DENIED_SCOPE pentru acea cheie.

Funcționează și prin MCP (Claude, ChatGPT, Cursor)?

Da. Fiecare endpoint e disponibil ca tool MCP (localitati_mfp, localitati_mfp_cauta), cu același cost.

Integrează Localități cu SIRUTA și cod poștal

Cont gratuit, cheia API imediat. Plătești doar cererile reușite; 404 și erorile nu consumă credite.

Creează cont gratuitDocumentația completăPrețuri →