Informacje ogólne
Budowa API Statystyki NFZ - Leki w Chemioterapii zrealizowana została w ramach projektu „Otwarte Dane – dostęp, standard, edukacja” w ramach programu Operacyjnego Polska Cyfrowa na lata 2014-2020.
Swagger i API Statystyki NFZ – Leki w Chemioterapii
W celu ułatwienia korzystania z API Statystki NFZ - Leki w Chemioterapii zdecydowaliśmy się dodać do dokumentacji Swagger UI. Jest to narzędzie umożliwiające w prosty sposób wizualizację i interakcję z zasobami API bez konieczności implementowania. Narzędzie dostępne jest w menu w sekcji Swagger
Standardowy mechanizm wyszukiwania danych
API Statystki NFZ - Leki w Chemioterapii oferuje mechanizmy wyszukiwania z filtrowaniem pełnotekstowym po konkretnych polach oraz stronicowanie. Wszystkie parametry wyszukiwania podaje się w części query zaraz po przeszukiwanym zasobie porzedzając go znakiem pytajnika.(?)
Podaczas wyszukiwania w cześci query możemy używać standardowych pól:
page - numer strony wyników do zwrócenia. Strony numerowane są od 1. Domyślna ilość wyników na stronie opisana jest w dokumentacji Swagger UI.
limit - ilość wyników zróconych na stronie. Wartości domyślne i maksymalne zostały opisane szczegółowo w dokumentacji Swagger UI.
format - określa format zwracanych wyników. Domyślnie dane zwracane są w formacie json — JavaScript object notation.
Pozostałe pola filtrowania pełnetekstowego opisuje szczegółowo dokumentacja Swagger UI dla każdego przeszukiwanego zasobu.
Zasoby
Dane statystyczne zostały podzielone na trzy główne sekcje
Chemioterapia
W tej sekcji znajduje się 6 zasobów zwracających dane statystyczne dotyczące wykonań refundacji aptecznych.
/active-substance-costs/active-substance-costs-by-gender/active-substance-costs-by-age/monthly-provisions/yearly-provisions/available-periods
/active-substance-costs
Zasób zwraca dane statystyczne dotyczące kosztów substancji czynnych w chemioterapii, określonych parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt active-substance-costs
(SwaggerUi).
/active-substance-costs-by-gender
Zasób zwraca dane statystyczne dotyczące kosztów substancji czynnych w chemioterapii w podziale na płeć pacjenta, określonych parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt active-substance-costs-by-gender
(SwaggerUi).
/active-substance-costs-by-age
Zasób zwraca dane statystyczne dotyczące kosztów substancji czynnych w chemioterapii w podziale na grupy wiekowe pacjenta, określonych parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt active-substance-costs-by-age
(SwaggerUi).
/monthly-provisions
Zasób zwraca dane statystyczne dotyczące kwoty refundacji NFZ i liczbie pacjentów w podziale na miesiące określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt monthly-provisions
(SwaggerUi).
/yearly-provisions
Zasób zwraca dane statystyczne dotyczące kwoty refundacji NFZ i liczbie pacjentów w podziale na lata określona parametrami wyszukiwania.
Wynik żądania zgodnie ze strukturą zwraca obiekt yearly-provisions
(SwaggerUi).
/available-periods
Zasób zwraca informacje o dostępnym zakresie dat dla których dostępne są dane statystyczne.
Wynik żądania zgodnie ze strukturą zwraca obiekt available-periods
(SwaggerUi).
Słowniki
W teje sekcji znajduje się 2 zasoby słownikowe.
/active-substances
Zasób zwraca informacje o dostępnych substancjach czynnych dla których dostępne są dane statystyczne.
Wynik żądania zgodnie ze strukturą zwraca obiekt active-substances
(SwaggerUi).
Info
W sekcji "Info" znajduje się zasób zwracający aktualną wersję API.
Struktura danych
Dane z API zwracane są zgodnie ze standardem JSON API. W każdej odpowiedzi znajduje się co najmniej jedna z poniższych sekcji:
z zastrzeżeniem, że data i errors nie mogą wystąpić razem w jednej odpowiedzi.
links
Ponieważ zasoby zwracające listę wyników są stronicowane (25 wyników na stronę),
dodatkowo w odpowiedziach dodawana jest sekcja links, ułatwiająca poruszanie się po API (HATEOAS).
Dostępnych w sekcji jest 5 linków:
first- do pierwszej strony wyników,prev- do następnej strony wyników,self- do aktualnej strony wyników,next- do następnej strony wyników,last- do ostaniej strony wyników,
Na przykład poniższe żądanie:
https://api.nfz.gov.pl/app-stat-api-ch/sections?section=ocz
zwróci listę sekcji JGP zawierających fragment "ocz":
{
"meta": {
"@context": "/schemas/#section",
...
"count": 2,
"page": 1,
"limit": 10
...
},
"links": {
"first": "/sections?page=1&limit=10§ion=ocz",
"prev": null,
"self": "/sections?page=1&limit=10§ion=ocz",
"next": null,
"last": "/sections?page=1&limit=10§ion=ocz"
},
"data": [
"B - Choroby oczu",
"L - Choroby układu moczowo-płciowego"
]
}
Należy zwrócić uwagę na link prev, który nie zawiera żadnej wartości (null).
Spowodowane jest to użyciem domyślnych wartości paramterów (ponieważ ich nie przekazano). Domyślnie parametr page = 1, dlatego opdowiedź z API zawiera pierwszą stronę wyników
dla której poprzednia nie istnieje.
data
Sekcja data zawiera dane pasujące do kryteriów wyszukiwania. W tej sekcji możemy odnaleźć różnego rodzaju struktury w zależności od przeszukiwanego zasobu.
Przykład opowiedzi na zapytanie wyszukujące dane statystyczne dot. kosztów leczenia w programie lekowym zawierającym słowo czerniak
{
"meta": {
"@context": null,
"count": 3,
"title": null,
"page": 1,
"url": null,
"limit": 10,
"provider": "Narodowy Fundusz Zdrowia",
"date-published": "2019-07-30T15:26:00+01:00",
"date-modified": "2019-07-31T18:46:13+02:00",
"description": null,
"keywords": null,
"language": "PL",
"content-type": "application/json; charset=utf-8",
"is-part-of": null
},
"links": {
"first": "/app-stat-api-pl/drug-costs-by-drug-program?page=1&limit=10&format=json&drugProgram=czerniak",
"prev": null,
"self": "/app-stat-api-pl/drug-costs-by-drug-program?page=1&limit=10&format=json&drugProgram=czerniak",
"next": null,
"last": "/app-stat-api-pl/drug-costs-by-drug-program?page=1&limit=10&format=json&drugProgram=czerniak",
"related": null
},
"data": {
"sums": {
"refund": 399608888.29
},
"data": [
{
"drug-program-code": "03.0001.359.02",
"drug-program-mz-code": "B.59",
"drug-program-name": "LEKI W PROGRAMIE LEKOWYM - LECZENIE CZERNIAKA SKÓRY LUB BŁON ŚLUZOWYCH",
"number-of-patients": 1410,
"refund": 212791910.8
},
{
"drug-program-code": "03.0001.372.02",
"drug-program-mz-code": "B.72",
"drug-program-name": "LEKI W PROGRAMIE LEKOWYM - LECZENIE CZERNIAKA SKOJARZONĄ TERAPIĄ DABRAFENIBEM I TRAMETYNIBEM",
"number-of-patients": 532,
"refund": 123241554.4
},
{
"drug-program-code": "03.0001.348.02",
"drug-program-mz-code": "B.48",
"drug-program-name": "LEKI W PROGRAMIE LEKOWYM - LECZENIE CZERNIAKA SKÓRY",
"number-of-patients": 310,
"refund": 63575423.09
}
]
}
}
Lista wszystkich możliwych schematów zwracanych w sekcji data została opisana w osobnej sekcji dokumentacji - Schematy.
errors
Podczas pracy z API można natrafić na błędy, które w sposób zgodny ze standardem zawierają możliwie jak najwięcej informacji, ułatwiających rozwiązanie problemu.
Przykładowy błąd zwracany w przypadku gdy zostanie przekazany zbyt długi paramter (drugProgram):
{
"errors": [
{
"id": "bf99b2fa-8b84-4488-9e6f-85e324dea9ff",
"errorr-result": "Cannot return results",
"errorr-reason": "Invalid length for {drugProgram} parameter",
"errorr-solution": "Provide proper value for attribute",
"error-help": "/errors/#6201001",
"error-code": 6201001
}
]
}
Struktura odpowiedzi została opisana w osobnej sekcji dokumentacji - Schematy.
Lista możliwych błędów została opisana w osobnej sekcji dokumentacji - Opis błędów
meta
Szczegóły dotyczące metadanych zostały opisanę w osobnej sekcji dokumentacji - Metadane