API.adresy.app
Przewodnik dla początkujących

API bez tajemnic

Nie wiesz co to API? Za 10 minut będziesz pobierać polskie adresy w Pythonie. Żadnej wiedzy technicznej nie wymagamy.

Załóż darmowe konto →
Krok 1

Co to w ogóle jest API?

API to skrót od Application Programming Interface — czyli sposób, w jaki programy rozmawiają ze sobą. Brzmi skomplikowanie, ale w praktyce jest to coś, czego używasz na co dzień.

🍕

Analogia z restauracją

Wyobraź sobie restaurację. Ty (Twój program) siedzisz przy stoliku i chcesz pizzę. Nie idziesz do kuchni — zamiast tego mówisz kelnerowi (API) czego chcesz. Kelner idzie do kuchni (serwera z danymi), odbiera pizzę (dane adresowe) i przynosi Ci z powrotem.

🗺️

API Adresy.app — konkrety

Wysyłasz do nas: "Co wiesz o adresie Kościuszki 14 Kraków?"
My odpowiadamy: kod pocztowy, współrzędne GPS, kod TERYT, ID punktu w PRG — wszystko w ustandaryzowanym formacie, w ułamku sekundy.

Krok 2

Jak wygląda rozmowa z API?

Każda komunikacja z API składa się z dwóch etapów: zapytanie (request) i odpowiedź (response). Dokładnie jak rozmowa.

💻
Twój program
wysyła zapytanie
adres + klucz API
▶
🌐
Internet
HTTPS
 
▶
🖥️
Serwer API
przetwarza
JSON z danymi
▶
📦
Dane
gotowe do użycia

Cały ten proces trwa zwykle poniżej 100 milisekund — szybciej niż mrugnięcie okiem.

💡

Co to JSON? To prosty format tekstu — lista par "nazwa: wartość". Twój program potrafi go odczytać w jednej linii kodu. Przykład zobaczysz za chwilę.

Krok 3

Klucz API — Twoja przepustka

Żeby serwer wiedział, kto pyta — i żeby mógł naliczać limity — każde zapytanie musi zawierać klucz API. To długi ciąg liter i cyfr, który jest przypisany do Twojego konta.

PRZYKŁADOWY KLUCZ 
sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789
⚠️

Ważne: klucz API jest jak hasło. Nie wrzucaj go do publicznych repozytoriów (GitHub), nie udostępniaj. Jeśli wycieknie — od razu wygeneruj nowy w panelu klienta.

1

Załóż darmowe konto

Wejdź na api.adresy.app/auth/register. Potrzebujesz tylko adresu email.

2

Wygeneruj klucz API

W Panelu klienta → Klucze API kliknij "Generuj nowy klucz". Pojawi się Twój unikalny klucz — skopiuj go.

3

Gotowe — zacznij pytać API

Klucz dołączasz do każdego zapytania jako parametr api_key=. Poniżej pokażemy jak dokładnie.

Krok 4

Jak zbudować zapytanie?

Zapytanie do API to zwykły adres URL — taki jak w przeglądarce, tylko z danymi. Rozbijmy go na części:

Anatomia zapytania

https://api.adresy.app /api/v1/match ? q = Kościuszki+14+Kraków & api_key = TWOJ_KLUCZ_API
Adres serwera (zawsze taki sam)
Endpoint (co chcesz zrobić)
Nazwa parametru
Wartość parametru

Możesz to otworzyć prosto w przeglądarce — wklej URL, podmień klucz, naciśnij Enter. Zobaczysz surowy JSON.

✅

Przetestuj teraz — wejdź na api.adresy.app i wpisz adres w wyszukiwarce, lub otwórz ten link po wklejeniu swojego klucza.

Krok 5

Co dostajesz w odpowiedzi?

Odpowiedź przychodzi jako JSON — możesz go czytać jak słownik: każde pole ma nazwę i wartość. Oto przykład dla zapytania o "Kościuszki 14 Kraków":

ODPOWIEDŹ API (JSON) — GET /api/v1/match?q=Marszalkowska+1+Warszawa
{
  "results": [{
    "input":  "Marszalkowska 1 Warszawa",
    "status": "matched",
    "match": {
      "ulica_norm":  "ul. Marszałkowska",
      "nr_budynku":  "1",
      "miejscowosc": "Warszawa",
      "wojewodztwo": "MAZOWIECKIE",
      "kod_pocztowy":"00-624",
      "dzielnica":   "Śródmieście",
      "lat": 52.2143,
      "lon": 21.0210,
      "teryt_simc":  "0919810",
      "teryt_ulic":  "12400",
      "id_prg":      "PL.PZGIK.200_ed1b481b-...",
      "score": 1.0
    }
  }]
}
"status"Wynik dopasowania: matched = znaleziono, not_found = brak w bazie, ambiguous = kilka pasujących, low_confidence = niepewne
"score"Pewność dopasowania od 0 do 1. 1.0 = pewne. Poniżej 0.7 warto sprawdzić ręcznie.
"ulica_norm"Ustandaryzowana nazwa ulicy z bazy PRG (GUGiK) — oficjalnych danych państwowych
"lat" / "lon"Współrzędne GPS gotowe do użycia w mapach (Google Maps, Leaflet, OpenStreetMap)
"teryt_simc""id_prg"Identyfikatory z rejestrów państwowych — przydatne do integracji z GUS, CEIDG, systemami kadastrowymi
Demo

Wypróbuj teraz — bez kodu

Wpisz dowolny polski adres i kliknij Szukaj. Wyślemy zapytanie do API i zobaczysz prawdziwą odpowiedź.

Live demo — prawdziwe zapytanie API 

            

        

    


    
    

        
Bonus

        
Dekoduj TERYT — od kodu do pełnego adresu

        
Jeśli masz w bazie kody TERYT (SIMC, ULIC) i chcesz je zamienić na czytelne adresy — jest do tego dedykowany endpoint. Przyjmuje kod w trzech formatach i zwraca pełną hierarchię: województwo → powiat → gmina → miejscowość → dzielnica → ulica → numer → kod pocztowy.


        

            

                
SIMC → miejscowość

                ?simc=0986283
                
Wrocław, pow. Wrocław, woj. DOLNOŚLĄSKIE

            

            

                
ULIC → ulica

                ?ulic=19357
                
Rynek, Wrocław — wystąpuje w 1 miejscowości

            

            

                
SIMC#ULIC#NR → adres punktowy

                ?simc=0986283%2319357%231
                
Rynek 1, Wrocław, kod 50-106, GPS: 51.109, 17.033

            

        


        

            

                

                PYTHON
                
            

            


# Zdekoduj listę kodów SIMC z bazy danych
import httpx

BASE = "https://api.adresy.app/api/v1"
KEY  = "sk_live_twoj_klucz"

kody_simc = ["0986283", "0950463", "0918123"]  # Wrocław, Kraków, Warszawa

for simc in kody_simc:
    r = httpx.get(f"{BASE}/teryt/decode",
        params={"simc": simc},
        headers={"Authorization": f"Bearer {KEY}"})
    d = r.json()
    if d["found"]:
        print(f"{simc}: {d['miejscowosc']}, pow. {d['powiat']}, woj. {d['wojewodztwo']}")
        if d.get("dzielnice"):
            print(f"  Dzielnice: {', '.join(x['dzielnica_nazwa'] for x in d['dzielnice'][:3])}...")


            

        


        

            💡
            
W zakładce Narzędzia → Dekoduj TERYT i współrzędne na stronie głównej możesz dekodować kody interaktywnie — bez pisania kodu. Obsługuje też format SIMC-ULIC-NR używany w API dopasowania.

        

    


    
    

        
Krok 6

        
Twój pierwszy skrypt w Pythonie

        
Masz Pythona? Poniższy skrypt pobiera dane adresowe w kilku linijkach. Biblioteka requests jest standardem — pewnie już ją masz.


        

            

                

                PYTHON
                
            

            


# Krok 1: zainstaluj bibliotekę (tylko raz)
# pip install requests

import requests

# Krok 2: wpisz swój klucz API
API_KEY = "wpisz_tu_swoj_klucz"

# Krok 3: wyślij zapytanie
odpowiedz = requests.get(
    "https://api.adresy.app/api/v1/match",
    params={
        "q": "Kościuszki 14 Kraków",
        "api_key": API_KEY,
    }
)

# Krok 4: odczytaj wynik
dane = odpowiedz.json()
wynik = dane["results"][0]    # pierwszy (i jedyny) wynik
dopasowanie = wynik["match"]

print(f"Status: {wynik['status']}")
print(f"Ulica: {dopasowanie['ulica_norm']} {dopasowanie['nr_budynku']}")
print(f"Kod pocztowy: {dopasowanie['kod_pocztowy']}")
print(f"GPS: {dopasowanie['lat']}, {dopasowanie['lon']}")

            

        


        
Wynik działania skryptu:


        

            

                

                WYNIK
            

            


Status: matched
Ulica: ul. Kościuszki 14
Kod pocztowy: 30-105
GPS: 50.0614, 19.9356

            

        

    


    
    

        
Krok 7

        
Wiele adresów naraz — pętla

        
Masz listę adresów do sprawdzenia? Prosta pętla wystarczy:


        

            

                

                PYTHON
                
            

            


import requests
import time

API_KEY = "wpisz_tu_swoj_klucz"

adresy = [
    "Kościuszki 14 Kraków",
    "Marszałkowska 1 Warszawa",
    "Świdnicka 8/10 Wrocław",
]

for adres in adresy:
    resp = requests.get(
        "https://api.adresy.app/api/v1/match",
        params={"q": adres, "api_key": API_KEY}
    )
    wynik = resp.json()["results"][0]

    if wynik["status"] == "matched":
        kod = wynik["match"]["kod_pocztowy"]
        print(f"✓ {adres} → {kod}")
    else:
        print(f"✗ {adres} → {wynik['status']}")

    time.sleep(0.05)  # krótka przerwa — szanuj limity

            

        


        

            ⚡
            
Wskazówka: na planie Starter możesz wysyłać 200 zapytań na minutę. Dla dużych plików (tysiące adresów) możesz też skorzystać z wbudowanego narzędzia do importu plików CSV/Excel na stronie głównej.

        

    


    
    

        
Krok 8

        
Co gdy coś pójdzie nie tak?

        
API zawsze zwraca kod HTTP. Trzy sytuacje, które warto obsłużyć:


        

            

                

                PYTHON — OBSŁUGA BŁĘDÓW
                
            

            


resp = requests.get(
    "https://api.adresy.app/api/v1/match",
    params={"q": adres, "api_key": API_KEY}
)

if resp.status_code == 200:
    wynik = resp.json()["results"][0]
    # wszystko OK — przetwarzaj dane

elif resp.status_code == 401:
    print("Błędny klucz API — sprawdź api_key=")

elif resp.status_code == 429:
    print("Za dużo zapytań — poczekaj chwilę")
    time.sleep(60)  # poczekaj minutę i spróbuj ponownie

else:
    print(f"Błąd: {resp.status_code}")

            

        


        

            

                
200 OK

                
Zapytanie się powiodło. Dane są w JSON.

            

            

                
401 Unauthorized

                
Brak lub błędny klucz API.

            

            

                
429 Too Many Requests

                
Przekroczono limit zapytań na minutę. Spowolnij.

            

        

    


    
    

        
Cennik

        
Ile to kosztuje?

        
Zacznij za darmo — plan Free wystarczy do testów i małych projektów.


        

            

                
Free

                
0 zł

                
30 zapytań/min
3 000 zapytań/miesiąc
Idealny na start

            

            

                
Popularne

                
Starter

                
39 zł /mc

                
200 zapytań/min
100 000 zapytań/miesiąc
Dla małych sklepów

            

            

                
Business

                
299 zł /mc

                
1 200 zapytań/min
10 000 000 zapytań/miesiąc
Dla dużych integracji

            

        

    


    
    

        
Bez kodu

        
Nie piszesz w Pythonie? Nie musisz.

        
Adresy.app to zwykłe API HTTP — działa z każdym narzędziem no-code i automatyzacyjnym. Wpisujesz URL, podajesz klucz i gotowe.


        


            
            

                

                    
M

                    

                        
Make.com

                        
dawniej Integromat

                    

                

                
Waliduj adresy z formularzy, arkuszy Google, CRM-ów. Bez pisania kodu — klikasz i łączysz moduły.

                
Jak zacząć:

                
    
                    
  1. Dodaj moduł HTTP → Make a request
    2. 
                    
  2. URL: https://api.adresy.app/api/v1/match
    3. 
                    
  3. Method: GET
    4. 
                    
  4. Query string: q={{adres}} i api_key=TWOJ_KLUCZ
    5. 
                    
  5. Parse response: Yes → dane dostępne jako zmienne
    6. 
                

            


            
            

                

                    
n

                    

                        
n8n

                        
open-source, self-hosted

                    

                

                
Automatyzacje na własnym serwerze. Idealny do integracji z własną bazą danych, WooCommerce, Shopify.

                
Jak zacząć:

                
    
                    
  1. Dodaj node HTTP Request
    2. 
                    
  2. Method: GET
    3. 
                    
  3. URL: https://api.adresy.app/api/v1/match
    4. 
                    
  4. Add parameter: q = {{ $json.adres }}
    5. 
                    
  5. Add parameter: api_key = TWOJ_KLUCZ
    6. 
                

            


            
            

                

                    
Z

                    

                        
Zapier

                        
najpopularniejsza automatyzacja

                    

                

                
Połącz z tysiącami aplikacji: Google Sheets, Notion, HubSpot, Gmail, Typeform i innymi.

                
Jak zacząć:

                
    
                    
  1. Dodaj action Webhooks by Zapier → GET
    2. 
                    
  2. URL: https://api.adresy.app/api/v1/match?q=ADRES&api_key=KLUCZ
    3. 
                    
  3. Kliknij Test & Review
    4. 
                    
  4. Pola z odpowiedzi (results__0__match__kod_pocztowy) są dostępne w kolejnych krokach
    5. 
                

            


            
            

                

                    
G

                    

                        
Google Sheets

                        
Apps Script

                    

                

                
Waliduj adresy bezpośrednio w arkuszu kalkulacyjnym — formuła pobiera dane dla każdego wiersza.

                
Skrypt (Narzędzia → Apps Script):

                


function pobierzKod(adres) {
  var url = "https://api.adresy.app/api/v1/match?q="
    + encodeURIComponent(adres)
    + "&api_key=TWOJ_KLUCZ";
  var resp = UrlFetchApp.fetch(url);
  var dane = JSON.parse(resp.getContentText());
  return dane.results[0].match.kod_pocztowy;
}

                

                
Użyj w komórce: =pobierzKod(A2)

            


        


        

            💡
            
Wspólna zasada dla wszystkich narzędzi: URL to zawsze https://api.adresy.app/api/v1/match, metoda GET, parametry q=adres i api_key=klucz. Jeśli narzędzie obsługuje nagłówki HTTP, możesz też przesłać klucz jako X-API-Key: TWOJ_KLUCZ zamiast w URL.

        

    


    
    

        
Bonus

        
Autouzupełnianie adresów

        
Chcesz dodać do formularza podpowiedzi w czasie rzeczywistym? API udostępnia trzy kaskadowe endpointy — wpisanie kolejnych części adresu zawęża wyniki do konkretnego budynku.


        
Krok 1 — znajdź miejscowość

        

            

                

                HTTP
            

            


GET /api/v1/miejscowosci?q=Wrocław&limit=5&api_key=TWOJ_KLUCZ

            

        

        

            

                

                JSON
            

            


[{ "sym": "0986283", "nazwa": "Wrocław", "label": "Wrocław (Wrocław, dolnośląskie)" }]

            

        


        
Krok 2 — znajdź ulicę (używając sym z kroku 1)

        

            

                

                HTTP
            

            


GET /api/v1/ulice?q=Świdnicka&sym=0986283&limit=5&api_key=TWOJ_KLUCZ

            

        

        

            

                

                JSON
            

            


[{ "sym_ul": "22461", "nazwa_pelna": "ul. Świdnicka", "label": "ul. Świdnicka" }]

            

        


        
Krok 3 — pobierz numery budynków (używając sym + sym_ul)

        

            

                

                HTTP
            

            


GET /api/v1/numery?sym=0986283&sym_ul=22461&limit=10&api_key=TWOJ_KLUCZ

            

        

        

            

                

                JSON
            

            


["1", "2", "3", "4", ...]

            

        


        
Krok 4 — pobierz pełne dane adresu (po wyborze numeru)

        

            

                

                HTTP
            

            


GET /api/v1/lookup/autofill?sym=0986283&sym_ul=22461&nr=1&api_key=TWOJ_KLUCZ

            

        

        

            

                

                JSON
            

            


{
  "found": true,
  "miejscowosc": "Wrocław",
  "ulica": "ul. Świdnicka",
  "nr_budynku": "1",
  "kod_pocztowy": "50-064",
  "lat": 51.108803,
  "lon": 17.032651
}

            

        


        

            💡
            
Autouzupełnianie jest dostępne od planu Mini. Plan Free obsługuje walidację i wyszukiwanie — bez podpowiedzi w czasie rzeczywistym. Porównaj plany →

        

    


    
    

        
Gotowy, żeby zacząć?

        
Załóż darmowe konto, wygeneruj klucz API i wyślij pierwsze zapytanie w 5 minut.

        Załóż darmowe konto →