Ce este?

Un serviciu web care permite returnarea codului postal pe baza unei cereri. Cererea va fi trimisa folosind un format URI bine definit, iar ca raspuns vor fi suportate mai multe formate de serializare (XML, JSON, RDF, TXT).

Cui se adreseaza?

Dezvoltatorilor de aplicatii web care proceseaza informatii postale. De exemplu, intr-un magazin online pentru aflarea codului postal al adresei de expediere.

Ghid API

Cerere

Sus

Cererea poate fi trimisa utilizand HTTP sau HTTPS (SSL). Utilizarea SSL imbunatateste securitatea datelor prin criptarea comunicarii intre server-ul tau si GeoHub.ro, protejandu-le de interceptarea de catre o terta parte. Va recomandam folosirea HTTPS.

In functie de informatia cautata (cod postal sau adresa), cererea API-ului poate cuprinde trei sau mai multi parametri. Orice cerere trebuie sa includa cheia primita la inregistrarea unei aplicatii (key) si poate preciza formatul corespunzator raspunsului (output) si limba utilizata la afisarea mesajelor (lang).

Parametru Necesar Valoare implicita Descriere
key da null cheia primita la inregistrarea unei aplicatii
output nu XML specifica formatul corespunzator raspunsului: XML, JSON, RDF, RAW
lang nu english specifica limba utilizata pentru mesaje: english, romana

Daca vrei sa afli codurile postale asociate unei adrese, vei utiliza o serie de parametri pentru a descrie adresa: county, city (pentru localitatile mici); county, city, location, unit, details (pentru localitati mari). Accesarea API-ului se realizeaza in aceasta situatie prin intermediul unei cereri de tip forward (parametrul general type nu este obligatoriu si implicit are valoarea forward).

https://api.geohub.ro/key/«api_key»/type/forward/output/«format»/lang/«language»/county/«county»/city/«city»/location/«location»/unit/«unit»/details/«details»
Parametru Necesar Valoare implicita Descriere
type nu forward specifica faptul ca cererea este de tip forward (stabileste codul postal pentru o locatie)
county da null specifica judetul corespunzator adresei pentru care se doreste codul postal
city da null specifica localitatea (oras, comuna, sat)
location da null pentru localitatile mari specifica adresa (strada, bulevard, piata, alee, etc.)
pentru localitati mici acest parametru nu este necesar
unit nu null specifica tipul elementului de identificare a unei adrese (nr - numar, bl - bloc)
details nu null specifica elementul de identificare corespunzator unei adrese

Daca stii codul postal si vrei sa afli ce adrese corespund acestuia, poti cauta direct dupa codul postal. Accesarea API-ului se realizeaza in aceasta situatie prin intermediul unei cereri de tip reverse (parametrul general type este obligatoriu si are valoarea reverse).

https://api.geohub.ro/key/«api_key»/type/reverse/output/«format»/lang/«language»/zip/«postal-code»
Parametru Necesar Valoare implicita Descriere
type da reverse specifica faptul ca cererea este de tip reverse (stabileste adresa pentru un cod postal)
zip da null codul postal pentru care se doreste adresa

Raspuns

Sus

Element Descriere
postal_code cod postal
county nume judet
city nume localitate
type tip adresa (strada, bulevard, piata, alee, etc.)
name nume adresa
unit tip element identificare adresa (nr - numar, bl - bloc)
details element identificare adresa (120, ZA3, W1)
https://api.geohub.ro/key/«api_key»/lang/romana/county/timis/city/timisoara/location/vasile-parvan

Implicit, API-ul trimite raspunsurile in format XML. Raspunsul furnizat de API poate fi returnat si in format JSON, RDF sau text (RAW).

<response>
<status>Cerere corecta</status>
<message>Succes</message>
<notes>Au fost identificate urmatoarele rezultate</notes>
<code>200_1</code>
<location id="0">
<postal_code>300223</postal_code>
<county>Timis</county>
<city>Timisoara</city>
<type>Bulevard</type>
<name>Parvan Vasile</name>
<unit></unit>
<details></details>
<score>1.00</score>
</location>
<unit_test>
<elapsed_time>0.0812</elapsed_time>
<memory_usage>2.06MB</memory_usage>
</unit_test>
</response>
Cod Status Mesaj Descriere
200_1 Cerere corecta Succes Au fost identificate urmatoarele rezultate.
200_2 Cerere corecta Nici un rezultat Nu a fost returnat nici un rezultat.

Mesaje de eroare

Sus

Daca cererea nu se realizeaza cu succes, API-ul returneaza un mesaj de eroare. Implicit, acesta este returnat in format XML, dar este disponibil si in format JSON sau text (RAW).

<error>
<status>status</status>
<message>mesaj</message>
<notes>descriere</notes>
<code>cod</code>
<unit_test>
<elapsed_time>durata</elapsed_time>
<memory_usage>memorie</memory_usage>
</unit_test>
</error>
Cod Status Mesaj Descriere
400_1 Cerere gresita Eroare in URI Cererea trebuie sa contina un parametru de tip cheie (key).
400_2 Cerere gresita Eroare in URI Cererea trebuie sa contina un parametru de tip cod postal (zip).
400_21 Cerere gresita Eroare in URI Cererea trebuie sa contina un parametru de tip cod postal valid (zip).
400_3 Cerere gresita Eroare in URI Cererea trebuie sa contina un parametru de tip judet (county).
400_31 Cerere gresita Eroare in URI Cererea trebuie sa contina un parametru de tip judet valid (county).
400_4 Cerere gresita Eroare in URI Cererea trebuie sa contina un parametru de tip oras (city).
400_41 Cerere gresita Eroare in URI Cererea trebuie sa contina o asociere corecta de tip oras-judet.
400_5 Cerere gresita Eroare in URI Cererea trebuie sa contina un parametru de tip locatie (location).
400_51 Cerere gresita Eroare in URI Cererea trebuie sa contina un parametru de tip locatie valid (location).
403_1 Acces interzis Cerere neautorizata Cheia API utilizata in cerere nu a fost recunoscuta.
403_2 Acces interzis Cont inactiv Cheia API nu a fost autorizata sau a fost dezactivata.
403_3 Acces interzis Numar de cereri depasit Capacitatea serviciului a fost depasita.