Logo jobtime.pl
jobtime.pl Strony API dla ofert pracy

Nawigacja

Na początek Menu

API dla ofert pracy

API JobTime.pl umożliwia integratorom dostęp do aktywnych ofert pracy publikowanych na portalu jobtime.pl. API jest dostępne wyłącznie pod domeną api.jobtime.pl i wymaga autoryzacji na podstawie adresu IP partnera.

Bazowy URL API: https://api.jobtime.pl

Wersja API: v1

Autoryzacja

Autoryzacja przez IP


Dostęp do API jest kontrolowany na podstawie adresu IP. Aby uzyskać dostęp:

  1. Skontaktuj się z administratorem JobTime.pl
  2. Podaj adresy IP, z których będą wykonywane zapytania
  3. Po aktywacji konta partnera, Twoje IP będzie automatycznie autoryzowane

Obsługiwane formaty IP:

  • Pojedynczy adres: 192.168.1.100
  • Zakres CIDR: 192.168.1.0/24
  • Wildcard: 192.168.1.*

Limity zapytań (Rate Limiting)

Każde konto partnera ma przypisane limity:

  • Limit na minutę: domyślnie 60 zapytań/minutę
  • Limit dzienny: domyślnie 10,000 zapytań/dzień

Nagłówki odpowiedzi zawierające informacje o limitach:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9999


W przypadku przekroczenia limitu, API zwróci kod 429 Too Many Requests.

Endpointy

1. Lista ofert pracy

Pobiera listę aktywnych ofert pracy opublikowanych w określonym dniu.

GET /v1/offers


Parametry wymagane


ParametrTypOpisdatestringWymagane. Data publikacji ofert w formacie YYYY-MM-DD

Parametry opcjonalne (filtrowanie)


ParametrTypOpispageintegerNumer strony (domyślnie: 1)limitintegerLiczba wyników na stronę (1-100, domyślnie: 25)querystringFraza wyszukiwania w nazwie stanowiska i treści ofertycitystringFiltruj po mieście (np. Warszawa, Kraków)branchintegerID branży (zobacz endpoint /v1/branches)klasyfikacjastringKod klasyfikacji zawodowej KZiS (np. 242101)work_typeintegerTyp pracy: 1 = umysłowa, 2 = fizycznawork_placeintegerMiejsce pracy: 1 = biuro, 2 = magazyn/hala, 3 = zdalna, 4 = hybrydowa, 5 = delegacje, 6 = na dworzeoffer_typeintegerRodzaj oferty: 1 = oferta pracy, 2 = konkurs, 3 = staż/praktyki, 4 = stała współpraca, 5 = praca tymczasowa, 6 = aplikacja bez oferty, 7 = praca sezonowacontract_typestringTyp umowy (można podać kilka oddzielonych przecinkiem): uop, uop_cz, b2b, zlec, innasalary_minintegerMinimalne wynagrodzenie (PLN brutto/miesięcznie)remotebooleanFiltruj tylko pracę zdalną (1 lub true)

Przykładowe zapytanie


curl -X GET "https://api.jobtime.pl/v1/offers?date=2026-02-11&city=Warszawa&limit=10"


Przykładowa odpowiedź


{
  "success": true,
  "data": {
    "offers": [
      {
        "id": 12345,
        "jobname": "Programista PHP",
        "company_name": "ExampleTech Sp. z o.o.",
        "location": {
          "city": "Warszawa",
          "country": "PL"
        },
        "publication_date": "2026-02-11",
        "expiration_date": "2026-03-11",
        "urls": {
          "details": "https://api.jobtime.pl/v1/offers/12345",
          "website": "https://jobtime.pl/praca/12345/programista-php",
          "content": "https://api.jobtime.pl/v1/offers/12345/content"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 120,
      "items_per_page": 25,
      "has_next_page": true,
      "has_prev_page": false
    },
    "filters_applied": {
      "date": "2026-02-11",
      "city": "Warszawa"
    }
  }
}


Uwaga: Pole urls.content pojawia się tylko dla partnerów z uprawnieniami do odczytu pełnej treści ofert.

2. Szczegóły oferty

Pobiera szczegółowe informacje o ofercie pracy (bez pełnej treści ogłoszenia).

GET /v1/offers/{id}


Parametry


ParametrTypOpisidintegerWymagane. Unikalny identyfikator oferty

Przykładowe zapytanie


curl -X GET "https://api.jobtime.pl/v1/offers/12345"


Przykładowa odpowiedź


{
  "success": true,
  "data": {
    "id": 12345,
    "jobname": "Programista PHP",
    "company": {
      "id": 567,
      "name": "ExampleTech Sp. z o.o.",
      "verified": true,
      "logo_url": "https://jobtime.pl/files/company_567_logo.png",
      "website": "https://exampletech.pl"
    },
    "location": {
      "city": "Warszawa",
      "country": "PL",
      "street": "ul. Przykładowa 10",
      "display": "Warszawa, ul. Przykładowa 10"
    },
    "dates": {
      "publication": "2026-02-11",
      "expiration": "2026-03-11"
    },
    "offer_type": "Oferta pracy",
    "work_type": "Umysłowa",
    "work_place": "Biuro",
    "remote_recruitment": true,
    "experience": "Kilkuletnie",
    "education": "Wyższe",
    "contract_types": [
      "Umowa o pracę",
      "B2B"
    ],
    "salary": {
      "uop": {
        "from": 12000,
        "to": 18000,
        "currency": "PLN",
        "period": "month"
      },
      "b2b": {
        "from": 15000,
        "to": 22000,
        "currency": "PLN",
        "period": "month"
      }
    },
    "requirements": [
      "PHP 8.x",
      "Laravel/Symfony",
      "MySQL/PostgreSQL",
      "Git"
    ],
    "branches": [
      {
        "id": 15,
        "name": "IT / Programowanie"
      }
    ],
    "benefits": [
      {
        "id": 1,
        "name": "Prywatna opieka medyczna"
      },
      {
        "id": 5,
        "name": "Elastyczne godziny pracy"
      }
    ],
    "classification": {
      "code": "251201",
      "name": "Programista aplikacji"
    },
    "urls": {
      "content": "https://api.jobtime.pl/v1/offers/12345/content",
      "website": "https://jobtime.pl/praca/12345/programista-php"
    }
  }
}


3. Pełna treść oferty

Pobiera pełną treść ogłoszenia (opis stanowiska, wymagania, obowiązki itp.).

Uwaga: Ten endpoint jest dostępny tylko dla partnerów z uprawnieniami can_read_content.

GET /v1/offers/{id}/content


Parametry


ParametrTypOpisidintegerWymagane. Unikalny identyfikator oferty

Przykładowe zapytanie


curl -X GET "https://api.jobtime.pl/v1/offers/12345/content"


Przykładowa odpowiedź


{
  "success": true,
  "data": {
    "id": 12345,
    "jobname": "Programista PHP",
    "content_html": "<h3>O firmie</h3><p>ExampleTech to dynamicznie rozwijająca się firma...</p><h3>Opis stanowiska</h3><p>Poszukujemy doświadczonego programisty PHP...</p>",
    "content_plain": "O firmie\n\nExampleTech to dynamicznie rozwijająca się firma...\n\nOpis stanowiska\n\nPoszukujemy doświadczonego programisty PHP...",
    "urls": {
      "details": "https://api.jobtime.pl/v1/offers/12345",
      "website": "https://jobtime.pl/praca/12345/programista-php"
    }
  }
}


Pola odpowiedzi


PoleTypOpisidintegerID ofertyjobnamestringNazwa stanowiskacontent_htmlstringPełna treść oferty w formacie HTMLcontent_plainstringPełna treść oferty jako czysty tekst (bez tagów HTML)urls.detailsstringURL do szczegółów oferty w APIurls.websitestringURL do oferty na stronie jobtime.pl

Odpowiedź przy braku uprawnień (403)


{
  "success": false,
  "error": "Forbidden",
  "message": "Twoje konto nie ma uprawnień do odczytu pełnej treści ofert."
}


4. Lista branż

Zwraca listę wszystkich dostępnych branż do filtrowania ofert.

GET /v1/branches


Przykładowe zapytanie


curl -X GET "https://api.jobtime.pl/v1/branches"


Przykładowa odpowiedź


{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Administracja biurowa"
    },
    {
      "id": 2,
      "name": "Bankowość / Finanse"
    },
    {
      "id": 15,
      "name": "IT / Programowanie"
    }
  ]
}


5. Lista miast


Zwraca listę miast, w których są aktywne oferty pracy.

GET /v1/cities


Przykładowe zapytanie


curl -X GET "https://api.jobtime.pl/v1/cities"


Przykładowa odpowiedź


{
  "success": true,
  "data": [
    {
      "city": "Białystok",
      "country": "PL"
    },
    {
      "city": "Gdańsk",
      "country": "PL"
    },
    {
      "city": "Kraków",
      "country": "PL"
    },
    {
      "city": "Warszawa",
      "country": "PL"
    }
  ]
}


6. Statystyki


Zwraca podstawowe statystyki portalu.

GET /v1/stats


Przykładowe zapytanie


curl -X GET "https://api.jobtime.pl/v1/stats"


Przykładowa odpowiedź


{
  "success": true,
  "data": {
    "active_offers": 15234,
    "total_companies": 4521,
    "offers_published_today": 342,
    "generated_at": "2026-02-11 13:45:22"
  }
}


Kody błędów

Kod HTTPZnaczenie200Sukces400Błąd walidacji (np. brakujący parametr date)403Brak autoryzacji / nieautoryzowany IP404Zasób nie znaleziony (np. oferta nie istnieje lub jest nieaktywna)429Przekroczono limit zapytań500Błąd serwera

Struktura odpowiedzi błędu


{
  "success": false,
  "error": "Error Type",
  "message": "Szczegółowy opis błędu"
}


Przykłady błędów

Brak parametru date (400)


{
  "success": false,
  "error": "Missing required parameter",
  "message": "Parametr \"date\" jest wymagany. Podaj datę publikacji ofert (format: YYYY-MM-DD)."
}


Nieautoryzowany IP (403)


{
  "success": false,
  "error": "Unauthorized",
  "message": "Brak dostępu do API. Twój adres IP nie jest autoryzowany. Skontaktuj się z administratorem."
}


Przekroczony limit (429)


{
  "success": false,
  "error": "Rate Limit Exceeded",
  "message": "Przekroczono dzienny limit zapytań (10000).",
  "retry_after": 3600
}


Najlepsze praktyki

Cachowanie odpowiedzi

Zalecamy cachowanie odpowiedzi API po stronie klienta:

  • Lista ofert: cache przez 5-15 minut
  • Szczegóły oferty: cache przez 30-60 minut
  • Lista branż/miast: cache przez 24 godziny

Obsługa błędów

  1. Zawsze sprawdzaj pole success w odpowiedzi
  2. Implementuj retry logic z exponential backoff przy błędach 5xx
  3. Przy błędzie 429, poczekaj czas podany w retry_after

Paginacja

Przy pobieraniu dużych zbiorów danych:

  1. Użyj parametru limit do kontrolowania rozmiaru strony
  2. Iteruj przez strony używając page
  3. Sprawdzaj has_next_page przed pobieraniem kolejnej strony

Przykład integracji (PHP)

<?php

class JobTimeApi {
    private string $baseUrl = 'https://api.jobtime.pl';
    
    public function getOffers(string $date, array $filters = []): array {
        $params = array_merge(['date' => $date], $filters);
        $url = $this->baseUrl . '/v1/offers?' . http_build_query($params);
        
        $response = file_get_contents($url);
        $data = json_decode($response, true);
        
        if (!$data['success']) {
            throw new Exception($data['message']);
        }
        
        return $data['data'];
    }
    
    public function getOfferDetails(int $offerId): array {
        $url = $this->baseUrl . '/v1/offers/' . $offerId;
        
        $response = file_get_contents($url);
        $data = json_decode($response, true);
        
        if (!$data['success']) {
            throw new Exception($data['message']);
        }
        
        return $data['data'];
    }
}

// Użycie
$api = new JobTimeApi();

// Pobierz oferty z dzisiaj z Warszawy
$offers = $api->getOffers('2026-02-11', [
    'city' => 'Warszawa',
    'work_place' => 3, // praca zdalna
    'limit' => 50
]);

foreach ($offers['offers'] as $offer) {
    echo $offer['jobname'] . ' - ' . $offer['company_name'] . "\n";
}


Kontakt

W przypadku pytań dotyczących API lub uzyskania dostępu:

  • Email: bok@jobtime.pl

Historia zmian

v1.0 (2026-02-11)

  • Początkowa wersja API
  • Endpointy: /v1/offers, /v1/offers/{id}, /v1/offers/{id}/content
  • Endpointy pomocnicze: /v1/branches, /v1/cities, /v1/stats
  • Autoryzacja przez IP
  • Rate limiting