• »
  • EODATA »
  • Podręcznik API katalogu EOData na NSIS

Podręcznik API katalogu EOData na NSIS

OData (Open Data Protocol) to protokół sieciowy służący do tworzenia i korzystania z interfejsów API RESTful. Chociaż EODATA ma podobną nazwę, są to archiwa danych z obserwacji Ziemi, do których można uzyskać dostęp za pośrednictwem linków zgodnych ze standardami OData.

Wymagania wstępne

Nr 1 Możliwość wysyłania żądań HTTP

Najprostszą formą wysłania żądania HTTP jest wykonanie adresu internetowego w przeglądarce. Większość przeglądarek zrozumie dane wyjściowe z witryny i przedstawi je w użyteczny sposób.

Z wiersza poleceń w systemie operacyjnym na komputerze stacjonarnym można użyć programu curl, który wykona adres, ale przedstawi go w czysto tekstowej postaci. Jeśli curl nie jest wstępnie zainstalowany, możesz zainstalować go samodzielnie. W Ubuntu 22.04 można użyć polecenia

sudo apt install curl

Inne dystrybucje Linuksa będą miały identyczne lub bardzo podobne polecenie.

W zależności od typu i wersji systemu operacyjnego, na którym działa curl, mogą wystąpić problemy z niektórymi znakami. Należy zapoznać się z odpowiednią dokumentacją.

Istnieją alternatywy dla curl, ale ich omówienie jest poza zakresem niniejszego artykułu.

Co zostanie omówione?

Bieżące informowanie o zmianach w Katalogu

OData

  • Struktura zapytania

    • Zapytanie według nazwy

    • Zapytanie według listy

    • Zapytanie o kolekcję produktów

    • Zapytanie według daty publikacji

    • Zapytanie według daty wykrywania

    • Wyszukiwanie według kryteriów geograficznych

    • Zapytanie według atrybutów

  • Opcja Orderby

  • Opcja Top

  • Opcja Skip

  • Opcja Count

  • Opcja Expand

    • Opcja Expand – Attributes

    • Opcja Expand – Assets

    • Opcja Expand – Locations

  • Opcja Select

  • Listing węzłów produktu

  • Obsługa błędów API

DeletedProducts OData API

  • Adres URL punktu końcowego

  • Struktura zapytania

  • Opcja filtrowania

  • Zapytanie według nazwy

  • Zapytanie według ID

  • Zapytanie według daty usunięcia

  • Zapytanie według przyczyny usunięcia

  • Zapytanie według kolekcji produktów

  • Zapytanie według daty wykrywania

  • Zapytanie według atrybutów

Dodatkowe opcje

  • Opcja Orderby

  • Opcja Expand

  • Opcja Skip

  • Opcja Top

  • Opcja Count

Bieżące informowanie o zmianach w katalogu

Aby zapewnić wydajne i stałe wyszukiwanie w katalogu EOData, zaleca się korzystanie z subskrypcji:

Subskrypcje te zapewniają najskuteczniejszy sposób informowania o nowo dodanych, zmodyfikowanych lub usuniętych produktach w katalogu.

Podstawowym celem usług subskrypcji jest umożliwienie użytkownikom otrzymywania w czasie rzeczywistym powiadomień o istotnych zdarzeniach zachodzących w katalogu EOData. Użytkownicy mogą dostosować swoje powiadomienia, określając parametry filtrowania w żądaniu subskrypcji.

OData

Struktura zapytania

Ogólnie rzecz biorąc, zapytanie OData składa się z elementów, które w tej dokumentacji nazywane są „opcjami”. Interfejs obsługuje następujące opcje wyszukiwania:

  • filter

  • orderby

  • top

  • skip

  • count

  • expand

Opcje wyszukiwania powinny być zawsze poprzedzone znakiem $, a kolejne opcje powinny być oddzielone znakiem &.

Kolejne filtry w opcji filter powinny być oddzielone operatorami and lub or. Można również użyć operatora Not, na przykład:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=not contains(Name,'S2') and ContentDate/Start gt 2022-05-03T00:00:00.000Z and ContentDate/Start lt 2022-05-03T00:10:00.000Z&$orderby=ContentDate/Start&$top=100

Aby przyspieszyć działanie zapytania, zaleca się ograniczenie zapytania według dat pozyskania, na przykład:

ContentDate/Start gt 2022-05-03T00:00:00.000Z and ContentDate/Start lt 2022-05-21T00:00:00.000Z

Opcja filtrowania

Zapytanie według nazwy

Aby wyszukać określony produkt według jego dokładnej nazwy:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=Name eq 'S1A_IW_GRDH_1SDV_20141031T161924_20141031T161949_003076_003856_634E.SAFE'

Aby wyszukać produkty, zawierające w nazwie S1A:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=contains(Name,'S1A') and ContentDate/Start gt 2022-05-03T00:00:00.000Z and ContentDate/Start lt 2022-05-21T00:00:00.000Z

Alternatywnie do opcji contains można użyć endswith i startswith, aby wyszukać produkty kończące się lub zaczynające od podanego ciągu znaków.

Zapytanie według listy

W przypadku, gdy użytkownik chce wyszukać wiele produktów według nazwy w jednym zapytaniu, można użyć metody POST:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products/OData.CSC.FilterList

Treść żądania:

{
    "FilterProducts":
    [
        {"Name": "S1A_IW_GRDH_1SDV_20141031T161924_20141031T161949_003076_003856_634E.SAFE"},
        {"Name": "S3B_SL_1_RBT____20190116T050535_20190116T050835_20190117T125958_0179_021_048_0000_LN2_O_NT_003.SEN3"},
        {"Name": "xxxxxxxx.06.tar"}
    ]
}

Zwracane są dwa wyniki, ponieważ nie istnieje produkt o nazwie xxxxxxxx.06.tar.

Zapytanie o kolekcję produktów

Aby wyszukać produkty w określonej kolekcji:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=Collection/Name eq 'SENTINEL-2' and ContentDate/Start gt 2022-05-03T00:00:00.000Z and ContentDate/Start lt 2022-05-03T00:11:00.000Z

Obecnie dostępne są następujące kolekcje:

SENTINEL-1

SENTINEL-2

SENTINEL-3

SENTINEL-5P

**SENTINEL-6

SENTINEL-1-RTC

LANDSAT-5

LANDSAT-7

LANDSAT-8

SMOS.

TERRAAQUA

**COP-DEM

ENVISAT.

S2GLC

Zapytanie według daty publikacji

Aby wyszukać produkty opublikowane między dwiema datami:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=PublicationDate gt 2019-05-15T00:00:00.000Z and PublicationDate lt 2019-05-16T00:00:00.000Z

Do zdefiniowania przedziału domkniętego można użyć parametrów ge i le:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=PublicationDate ge 2019-05-15T00:00:00.000Z and PublicationDate le 2019-05-16T00:00:00.000Z

Zapytanie według daty wykrywania

Aby wyszukać produkty pozyskanie między dwiema datami:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=ContentDate/Start gt 2019-05-15T00:00:00.000Z and ContentDate/Start lt 2019-05-16T00:00:00.000Z

Zazwyczaj istnieją dwa parametry opisujące ContentDate (daty pozyskania) dla produktu - Start i End. W zależności od tego, czego szuka użytkownik, parametry te można mieszać, na przykład:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=ContentDate/Start gt 2019-05-15T00:00:00.000Z and ContentDate/End lt 2019-05-15T00:05:00.000Z

Wyszukiwanie według kryteriów geograficznych

Aby wyszukać produkty przecinające określony wielokąt:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=OData.CSC.Intersects(area=geography'SRID=4326;POLYGON((12.655118166047592 47.44667197521409,21.39065656328509 48.347694733853245,28.334291357162826 41.877123516783655,17.47086198383573 40.35854475076158,12.655118166047592 47.44667197521409))') and ContentDate/Start gt 2022-05-20T00:00:00.000Z and ContentDate/Start lt 2022-05-21T00:00:00.000Z

Aby wyszukać produkty przecinające określony punkt:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=OData.CSC.Intersects(area=geography%27SRID=4326;POINT(-0.5319577002158441%2028.65487836189358)%27)

Uwagi:

  1. Funkcja MULTIPOLYGON nie jest obecnie obsługiwana.

  2. Wielokąt musi zaczynać się i kończyć w tym samym punkcie.

  3. Współrzędne muszą być podane w EPSG 4326

Zapytanie według atrybutów

Aby wyszukać produkty według atrybutów, należy zbudować filtr o następującej strukturze:

Attributes/OData.CSC.ValueTypeAttribute/any(att:att/Name eq '[Attribute.Name]' and att/OData.CSC.ValueTypeAttribute/Value eq '[Attribute.Value]')

gdzie

  • ValueTypeAttribute może przyjmować następujące wartości:

    • StringAttribute

    • DoubleAttribute

    • IntegerAttribute

    • DateTimeOffsetAttribute

  • [Attribute.Name] to nazwa atrybutu, która może przyjmować wiele wartości w zależności od kolekcji (Załącznik 1 - wkrótce).

  • eq przed [Attribute.Value] może być zastąpione przez le, lt, ge, gt w przypadku atrybutów Integer, Double lub DateTimeOffset.

  • [Attribute.Value] to konkretna wartość, której szuka użytkownik.

Aby uzyskać produkty z cloudCover < 40% między dwiema datami:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=Attributes/OData.CSC.DoubleAttribute/any(att:att/Name eq 'cloudCover' and att/OData.CSC.DoubleAttribute/Value le 40.00) and ContentDate/Start gt 2022-01-01T00:00:00.000Z and ContentDate/Start lt 2022-01-03T00:00:00.000Z&$top=10

Aby uzyskać produkty z cloudCover< 10% i productType=S2MSI2A i ASCENDING orbitDirection pomiędzy dwiema datami:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=Attributes/OData.CSC.DoubleAttribute/any(att:att/Name eq 'cloudCover' and att/OData.CSC.DoubleAttribute/Value lt 10.00) and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'S2MSI2A') and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'orbitDirection' and att/OData.CSC.StringAttribute/Value eq 'ASCENDING') and ContentDate/Start gt 2022-05-03T00:00:00.000Z and ContentDate/Start lt 2022-05-03T04:00:00.000Z&$top=10

Opcja Orderby

Opcja Orderby może być używana do sortowania produktów rosnąco (asc) lub malejąco (desc). Jeśli parametry asc lub desc nie zostaną określone, zasoby zostaną posortowane rosnąco.

Aby sortować produkty według ContentDate/Start malejąco:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=contains(Name,'S1A_EW_GRD') and ContentDate/Start gt 2022-05-03T00:00:00.000Z and ContentDate/Start lt 2022-05-03T03:00:00.000Z&$orderby=ContentDate/Start desc

Domyślnie, jeśli opcja orderby nie jest używana, wyniki nie są sortowane. Jeśli używana jest opcja orderby, używana jest również dodatkowa opcja orderby by id, dzięki czemu wyniki są w pełni sortowane i żadne produkty nie zostaną utracone podczas stronicowania wyników.

Dopuszczalne argumenty dla tej opcji to ContentDate/Start, ContentDate/End, PublicationDate, ModificationDate z sortowaniem asc, desc

Opcja Top

Opcja Top określa maksymalną liczbę elementów zwracanych przez zapytanie.

Aby ograniczyć liczbę wyników:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=contains(Name,%27S1A_EW_GRD%27)%20and%20ContentDate/Start%20gt%202022-05-03T00:00:00.000Z%20and%20ContentDate/Start%20lt%202022-05-03T12:00:00.000Z&$top=100

Domyślną wartością jest 20.

Dopuszczalne argumenty dla tej opcji to Integer <0,1000>.

Opcja Skip

Opcja Skip może być używana, aby pominąć określoną liczbę wyników. Przykładowym zastosowaniem tej opcji byłoby stronicowanie wyników, jednak ze względów wydajnościowych zalecamy ograniczanie zapytań z małymi interwałami czasowymi jako substytutu stosowania pomijania w bardziej ogólnym zapytaniu.

Aby pominąć określoną liczbę wyników:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=contains(Name,%27S1A_EW_GRD%27)%20and%20ContentDate/Start%20gt%202022-05-03T00:00:00.000Z%20and%20ContentDate/Start%20lt%202022-05-03T12:00:00.000Z&$skip=23

Domyślną wartością jest 0.

Za każdym razem, gdy w wyniku zapytania jest więcej produktów niż 20 (domyślna górna wartość), interfejs API udostępnia link nextLink na dole strony:

"@odata.nextLink": "https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=contains(Name,'S1A_EW_GRD')+and+ContentDate/Start+gt+2022-05-03T00:00:00.000Z+and+ContentDate/Start+lt+2022-05-03T12:00:00.000Z&$skip=20"

Dopuszczalne argumenty dla tej opcji to Integer <0,10000>

Opcja Count

Opcja Count umożliwia użytkownikom uzyskanie dokładnej liczby produktów pasujących do zapytania. Opcja ta jest domyślnie wyłączona, aby przyspieszyć działanie zapytania.

Aby uzyskać dokładną liczbę produktów dla danego zapytania:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=contains(Name,%27S1A_EW_GRD%27)%20and%20ContentDate/Start%20gt%202022-05-03T00:00:00.000Z%20and%20ContentDate/Start%20lt%202022-05-03T12:00:00.000Z&$count=True

Dopuszczalne argumenty dla tej opcji to True, true, 1, False, false, 0

Opcja Expand

Opcja Expand umożliwia użytkownikom wybór rodzaju informacji, które chcą zobaczyć w szczegółach.

Dopuszczalne argumenty dla tej opcji to Attributes, Assets, Locations.

Opcja Expand – Attributes

Aby zobaczyć pełne metadane wyników, ustaw wartość Attributes na Expand:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=contains(Name,%27S1A_EW_GRD%27)%20and%20ContentDate/Start%20gt%202022-05-03T00:00:00.000Z%20and%20ContentDate/Start%20lt%202022-05-03T12:00:00.000Z&$expand=Attributes

Dla każdego produktu lista tych atrybutów jest dostępna jako wartość klucza Attributes. W powyższym zapytaniu, w chwili pisania tego artykułu, dla pierwszego produktu na liście początek tej listy będzie wyglądał następująco:

../_images/eodata_catalogue_api_manual_01_creodias.png

Opcja Expand – Assets

Aby wyświetlić listę dodatkowych zasobów dla produktów, w tym quicklooków, użyj wartości Assets:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=Collection/Name%20eq%20%27SENTINEL-3%27%20and%20contains(Name,%20%27SL_2_FRP___%27)&$expand=Assets

Lista zasobów jest dostępna jako wartość klucza Assets. Dla pierwszego produktu znalezionego za pomocą powyższego zapytania (w chwili pisania tego artykułu) lista ta wygląda następująco:

"Assets": [
     {
       "Type": "QUICKLOOK",
       "Id": "312dbf31-85c6-4613-aefa-ed8f04e5c6eb",
       "DownloadLink": "https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Assets(312dbf31-85c6-4613-aefa-ed8f04e5c6eb)/$value",
       "S3Path": "/eodata/Sentinel-3/SLSTR/SL_2_FRP___/2020/11/27/S3A_SL_2_FRP____20201127T201256_20201127T201556_20201129T020232_0180_065_285_0900_LN2_O_NT_004.SEN3"
     }
]

W tym przykładzie lista ta zawiera tylko jeden element, dla którego Type to QUICKLOOK. Link do pobrania tego elementu jest dostępny jako wartość klucza DownloadLink:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Assets(312dbf31-85c6-4613-aefa-ed8f04e5c6eb)/$value

Pamiętaj, że możesz pobrać te zasoby za pomocą tych linków bez konieczności potwierdzania swojej tożsamości.

Opcja Expand – Locations

Produkty mogą być dostępne do pobrania w formie wyodrębnionej (nieskompresowanej) i/lub skompresowanej, w zależności od produktu.

Jeśli chcesz zobaczyć, jakie metody pobierania są dostępne dla wyszukiwanych produktów, przypisz wartość Locations do opcji expand:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=Collection/Name%20eq%20%27SENTINEL-1%27%20and%20contains(Name,%27RAW%27)&$orderby=ContentDate/Start%20desc&$top=10&$expand=Locations

Teraz powinna zostać wyświetlona listę lokalizacji jako wartość klucza Locations. Każda z tych lokalizacji reprezentuje jeden z dostępnych sposobów pobrania produktu i zawiera informacje takie jak rozmiar, suma kontrolna i link do pobierania.

Na przykład, w chwili pisania tego artykułu, dla pierwszego produktu zwróconego przez powyższe zapytanie, lista ta wygląda następująco:

"Locations": [
    {
      "FormatType": "Compressed",
      "DownloadLink": "https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products(d695b74e-5f82-4b4c-95be-f08a631fac53)/$zip",
      "ContentLength": 1575276240,
      "Checksum": [
        {
          "Value": "46336ae3fd72617177b6d6bd6ee755b3",
          "Algorithm": "MD5",
          "ChecksumDate": "2024-05-28T10:54:29.721000Z"
        }
      ],
      "EvictionDate": "2024-06-27T11:00:26.387Z"
    },
    {
      "FormatType": "Extracted",
      "DownloadLink": "https://catalogue.nsiscloud.polsa.gov.pl/data/v1/Products(d695b74e-5f82-4b4c-95be-f08a631fac53)/$value",
      "ContentLength": 1575275488,
      "Checksum": [
        {
          "Value": "054c188b645c4b8ce7ab7b65abc1a9f0",
          "Algorithm": "MD5",
          "ChecksumDate": "2024-05-28T11:01:34.881769Z"
        },
        {
          "Value": "2c1f95bfc5f88a455061a41f689222512e620fbda8ea2cdea5f5206c32472644",
          "Algorithm": "BLAKE3",
          "ChecksumDate": "2024-05-28T11:01:37.330063Z"
        }
      ],
      "S3Path": "/eodata/Sentinel-1/SAR/IW_RAW__0S/2024/05/28/S1A_IW_RAW__0SDV_20240528T102453_20240528T102523_054070_06930F_897A.SAFE"
    }
  ]

Jeśli chcesz pobrać skompresowaną formę tego produktu, możesz skorzystać z poniższego łącza:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products(d695b74e-5f82-4b4c-95be-f08a631fac53)/$zip

Aby pobrać ten produkt, musisz potwierdzić swoją tożsamość, w przeciwieństwie do sytuacji, gdy pobierasz zasoby, jak wyjaśniono w sekcji powyżej. Możesz to zrobić za pomocą tokena Keycloak - zobacz artykuł, do którego link znajduje się w sekcji „Co można zrobić dalej?”, aby dowiedzieć się więcej.

Opcja Select

Opcja Select pozwala użytkownikom ograniczyć żądane właściwości do określonego podzbioru dla każdego produktu, np. aby wybrać Nazwę i Id produktów:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$select=Name,Id

Lista nazw właściwości musi być oddzielona przecinkiem - może również zawierać dodatkową spację. Kolejność atrybutów w odpowiedzi jest przypisywana domyślnie i nie zależy od kolejności atrybutów określonych w zapytaniu użytkownika.

Parametr Id jest domyślnie dostarczany w odpowiedzi, nawet jeśli nie został zdefiniowany w opcji select.

Obecnie są dostępne te atrybuty:

Id

Name

ContentType

ContentLength

OriginDate

PublicationDate

ModificationDate

Online

EvictionDate

*S3Path

Checksum

ContentDate

Footprint

Geofootprint

Aby wybrać wszystkie dostępne atrybuty, można użyć symbolu * zamiast wyświetlania każdej nazwy właściwości osobno:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$select=*

Listing węzłów produktu

Możesz przeglądać pliki i katalogi znajdujące się w produkcie bez pobierania go, nawet jeśli nie masz autoryzacji.

Aby rozpocząć, wejdź na poniższy adres URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products(<PRODUCT_UUID>)/Nodes

gdzie <PRODUCT_UUID> to identyfikator produktu uzyskany za pomocą zapytania wyszukiwania. Jedną z metod uzyskania tego identyfikatora jest dostęp do adresu URL znajdującego się w sekcji Zapytanie według nazwy powyżej. Identyfikator można następnie znaleźć jako wartość klucza Id.

Po znalezieniu identyfikatora produktu i uzyskaniu dostępu do adresu URL kończącego się frazą Nodes wspomnianą powyżej, powinien być widoczny (jako wartość klucza uri) link, który pozwala wyświetlić zawartość katalogu głównego produktu.

Linki do plików i katalogów można znaleźć jako wartości kluczy uri. Można ich użyć, aby przejść dalej w strukturze katalogów.

Zasadniczo można przeglądać produkty z następującymi wzorcami adresów URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products(<PRODUCT_UUID>)/Nodes
https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products(<PRODUCT_UUID>)/Nodes(<NODE_NAME>)/Nodes
https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products(<PRODUCT_UUID>)/Nodes(<NODE_NAME>)/Nodes(<NODE_NAME>)/Nodes

gdzie

<PRODUCT_UUID>

to identyfikator produktu uzyskany przez zapytanie wyszukiwania

<NODE_NAME>

jest nazwą elementu (zwykłego pliku lub katalogu) wewnątrz produktu zwróconego w poprzedniej odpowiedzi listingu.

Każdy z węzłów reprezentuje plik lub katalog znaleziony w produkcie.

Tylko węzły będące katalogami mogą mieć listowaną zawartość. Jeśli katalog jest pusty, otrzymasz pustą listę:

{"result":[]}

Próba wyświetlenia dla węzła listy dla pliku również zwraca pustą listę.

Przykład:

Załóżmy, że chcemy przejrzeć produkt S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE. Najpierw musimy znaleźć jego identyfikator. Jednym ze sposobów, by to zrobić, jest użycie metody z sekcji Zapytanie według nazwy powyżej. W tym przypadku link użyty do uzyskania ID naszego produktu to:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products?$filter=Name eq 'S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE'

Wynik powinien wyglądać następująco:

{"@odata.context":"$metadata#Products","value":[{"@odata.mediaContentType":"application/octet-stream","Id":"db0c8ef3-8ec0-5185-a537-812dad3c58f8","Name":"S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE","ContentType":"application/octet-stream","ContentLength":0,"OriginDate":"2018-09-27T09:58:32.232Z","PublicationDate":"2018-09-27T10:00:58.635Z","ModificationDate":"2018-09-27T10:00:58.635Z","Online":true,"EvictionDate":"","S3Path":"/eodata/Sentinel-2/MSI/L1C/2018/09/27/S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE","Checksum":[],"ContentDate":{"Start":"2018-09-27T05:12:21.024Z","End":"2018-09-27T05:12:21.024Z"},"Footprint":"geography'SRID=4326;POLYGON ((71.341364137137 -48.727041539228, 71.646935006865 -48.789996101558, 71.593710420137 -48.929941890079, 71.537783906556 -49.075177891591, 71.48146556012 -49.220381137077, 71.424930990672 -49.365672690881, 71.368169948403 -49.511156280189, 71.310581782625 -49.656891295565, 71.287247481622 -49.715681890939, 70.387675347677 -49.732377517566, 70.360279246284 -48.744984111698, 71.341364137137 -48.727041539228))'","GeoFootprint":{"type":"Polygon","coordinates":[[[71.341364137137,-48.727041539228],[71.646935006865,-48.789996101558],[71.593710420137,-48.929941890079],[71.537783906556,-49.075177891591],[71.48146556012,-49.220381137077],[71.424930990672,-49.365672690881],[71.368169948403,-49.511156280189],[71.310581782625,-49.656891295565],[71.287247481622,-49.715681890939],[70.387675347677,-49.732377517566],[70.360279246284,-48.744984111698],[71.341364137137,-48.727041539228]]]}}]}

Jak widać w danych wyjściowych, identyfikator tego produktu to db0c8ef3-8ec0-5185-a537-812dad3c58f8. Link używany do przeglądania produktu będzie wyglądał następująco:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes

Odpowiedź:

{
   "result":[
      {
         "Id":"S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE",
         "Name":"S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE",
         "ContentLength":0,
         "ChildrenNumber":9,
         "Nodes":{
            "uri":"https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes"
         }
      }
   ]
}

Każdy węzeł na liście ma pole uri, które zawiera listę jego elementów podrzędnych.

Uzyskaj dostęp do jedynego adresu uri widocznego w powyższych danych wyjściowych, jest to:

https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes

Powinna teraz zostać wyświetlona lista elementów z katalogu głównego produktu. Oto niektóre (nie wszystkie) z nich:

{
  "result": [
    {
      "Id": "AUX_DATA",
      "Name": "AUX_DATA",
      "ContentLength": 0,
      "ChildrenNumber": 0,
      "Nodes": {
        "uri": "https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes(AUX_DATA)/Nodes"
      }
    },
    {
      "Id": "DATASTRIP",
      "Name": "DATASTRIP",
      "ContentLength": 0,
      "ChildrenNumber": 1,
      "Nodes": {
        "uri": "https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes(DATASTRIP)/Nodes"
      }
    },
    {
      "Id": "GRANULE",
      "Name": "GRANULE",
      "ContentLength": 0,
      "ChildrenNumber": 1,
      "Nodes": {
        "uri": "https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes(GRANULE)/Nodes"
      }
    }
  ]
}

Załóżmy, że chcesz przejrzeć zawartość katalogu DATASTRIP tego produktu. Aby to zrobić, przejdź do następującego linku widocznego na powyższych danych wyjściowych:

https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes(DATASTRIP)/Nodes

Ten katalog zawiera tylko jeden podkatalog:

{
  "result": [
    {
      "Id": "DS_EPAE_20180927T073143_S20180927T051218",
      "Name": "DS_EPAE_20180927T073143_S20180927T051218",
      "ContentLength": 0,
      "ChildrenNumber": 2,
      "Nodes": {
        "uri": "https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes(DATASTRIP)/Nodes(DS_EPAE_20180927T073143_S20180927T051218)/Nodes"
      }
    }
  ]
}

Dostęp do tego podkatalogu pokazuje, że zawiera on jeden plik i jeden katalog:

{
  "result": [
    {
      "Id": "MTD_DS.xml",
      "Name": "MTD_DS.xml",
      "ContentLength": 3116641,
      "ChildrenNumber": 0,
      "Nodes": {
        "uri": "https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes(DATASTRIP)/Nodes(DS_EPAE_20180927T073143_S20180927T051218)/Nodes(MTD_DS.xml)/Nodes"
      }
    },
    {
      "Id": "QI_DATA",
      "Name": "QI_DATA",
      "ContentLength": 0,
      "ChildrenNumber": 5,
      "Nodes": {
        "uri": "https://download.nsiscloud.polsa.gov.pl/odata/v1/Products(db0c8ef3-8ec0-5185-a537-812dad3c58f8)/Nodes(S2A_MSIL1C_20180927T051221_N0206_R033_T42FXL_20180927T073143.SAFE)/Nodes(DATASTRIP)/Nodes(DS_EPAE_20180927T073143_S20180927T051218)/Nodes(QI_DATA)/Nodes"
      }
    }
  ]
}

Obsługa błędów API

Po wykonaniu zapytania serwer może odrzucić żądanie i zwrócić kod błędu opatrzony dotyczącą go informacją. Do najczęściej zwracanych kodów błędów spowodowanych wystąpieniem problemu po stronie użytkownika należą:

  • 400 Bad request

  • 401 Unauthorized

  • 403 Forbidden

  • 422 Unprocessable Entity

Kod błędu: 400 Bad request

Przykładowa odpowiedź

400 Bad Request
{
   "detail": {
      "message": "Invalid field: Nmae",
      "request_id": "8e8f7bae-0487-412b-b70a-f486d0d6fd04"
   }
}

Błąd związany jest z błędną składnią zapytania bądź jego niepoprawnym formatowaniem. W wyniku przekazania nieprawidłowego zapytania serwer nie jest w stanie go obsłużyć i zwraca błąd. W wiadomości zostaje przekazana informacja pozwalająca na szybsze rozpoznanie, w którym miejscu należy wprowadzić poprawkę i czego ona dotyczy, np.:

  • „message”: „Invalid field: Nmae”

  • „message”: „Error during parsing at index 4”

Przed ponowieniem zapytania należy zapoznać się z dokumentacją dotyczącą konstruowania zapytań OData i poprawić składnię.

Kod błędu: 401 Unauthorized

Przykładowa odpowiedź

401 Unauthorized
{
   "error": "invalid_grant",
   "error_description": "Invalid user credentials"
}

Błąd występuje w przypadku podania niewłaściwych danych uwierzytelniających podczas generowania tokena.

Kod błędu: 403 Forbidden

Błąd nie zwraca wiadomości. Jego występowanie związane jest z brakiem dostępu do zasobu w sytuacji, gdy zostanie podany niepoprawny bądź wygasły token.

Przed ponowieniem zapytania należy upewnić się, że Bearer Token użytkownika jest poprawny.

Kod błędu: 422 Unprocessable Entity

Przykładowa odpowiedź

422 Unprocessable Entity
{
   "detail": [
      {
            "type": "less_than_equal",
            "loc": [
               "query",
               "$skip"
            ],
            "msg": "Input should be less than or equal to 10000",
            "input": "10001",
            "ctx": {
               "error": {}
            }
      }
   ]
}

Błąd związany jest z niespełnieniem walidacji semantycznej, na przykład, gdy zdefiniowany zostanie zbyt duży parametr „skip”, „top”, „count” bądź podane Id produktu będzie niepoprawne. Samo zapytanie pod względem składniowym przekazane jest w sposób właściwy. Zwrócona wiadomość zawiera informację dotyczącą popełnionego błędu.

Przed ponownym wysłaniem zapytania należy zapoznać się z dokumentacją oraz zastosować się do podanego komunikatu.

DeletedProducts OData API

Punkt końcowy DeletedProducts OData umożliwia użytkownikom dostęp do informacji o produktach usuniętych z katalogu. Ten punkt końcowy zapewnia wygodny sposób pobierania szczegółowych informacji o produktach, które zostały usunięte z katalogu. Korzystając z obsługiwanych operacji i opcji filtrowania, użytkownicy mogą skutecznie uzyskać dostęp do wymaganych informacji szczegółowych o usuniętych produktach. W przypadku punktu końcowego DeletedProducts OData żądania powinny być budowane w taki sam sposób, jak w przypadku punktu końcowego OData Products, ze zmianą adresu URL Products na DeletedProducts.

Adres URL punktu końcowego

Dostęp do usuniętego punktu końcowego OData można uzyskać za pomocą następującego adresu URL:

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts

Struktura zapytania

Punkt końcowy OData DeletedProducts obsługuje te same opcje wyszukiwania, co standardowy punkt końcowy OData Products. Aby uzyskać więcej informacji, przejdź do sekcji Struktura zapytania powyżej.

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=not contains(Name,'S1') and DeletionDate gt 2023-04-01T00:00:00.000Z and DeletionDate lt 2023-05-30T23:59:59.999Z&$orderby=DeletionDate&$top=20

UWAGA DOTYCZĄCA WYDAJNOŚCI

Aby przyspieszyć działanie zapytania, zdecydowanie zaleca się ograniczenie zapytania do określonych dat, na przykład:

DeletionDate gt 2022-05-03T00:00:00.000Z and DeletionDate lt 2023-05-03T00:00:00.000Z

Opcja filtrowania

Aby wyszukać produkty według właściwości, należy zbudować filtr, jak wyjaśniono w rozdziale o opcjach filtra powyżej.

Dopuszczalne właściwości produktów dla punktu końcowego OData DeletedProducts są następujące:

  • Name - wyszukiwanie określonego produktu według jego dokładnej nazwy.

  • Id - wyszukiwanie określonego produktu według jego identyfikatora.

  • DeletionDate - wyszukiwanie według daty usunięcia

  • DeletionCause - wyszukiwanie według przyczyny usunięcia

  • Collection/Name - wyszukiwanie w określonej kolekcji

  • OriginDate - wyszukiwanie według daty pochodzenia

  • ContentDate/Start i ContentDate/End - wyszukiwanie według daty wykrycia

  • Footprint - wyszukiwanie według kryteriów geograficznych

  • Attributes - wyszukiwanie według atrybutów produktu

Zapytanie według nazwy

Aby wyszukać usunięty produkt według jego dokładnej nazwy:

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=Name eq 'S2A_MSIL1C_20210404T112111_N0500_R037_T31VEG_20230209T101305.SAFE'

Zapytanie według ID

Aby wyszukać usunięty produkt według jego identyfikatora:

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts(29008eb1-1a51-48a8-9aec-288b00f7debe)

Zapytanie według daty usunięcia

Aby wyszukać produkty usunięte między dwiema datami włącznie:

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=DeletionDate ge 2023-04-26T00:00:00.000Z and DeletionDate le 2023-04-27T23:59:59.999Z

Zapytanie według przyczyny usunięcia

Aby wyszukać produkty usunięte z określonego powodu:

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=DeletionCause eq 'Duplicated product' or DeletionCause eq 'Corrupted product'

Dozwolone wartości parametru DeletionCause to:

  • Duplicated product

  • Missing checksum

  • Corrupted product

  • Obsolete product/Other

Zapytanie według kolekcji produktów

Aby wyszukać usunięte produkty w określonej kolekcji:

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=Collection/Name eq 'SENTINEL-2' and DeletionDate gt 2023-04-01T00:00:00.000Z and DeletionDate lt 2023-09-30T23:59:59.999Z

Dostępne kolekcje można znaleźć pod linkiem. Należy również pamiętać, że jest możliwe, że żaden z produktów nie został usunięty z dostępnych kolekcji.

Zapytanie według daty wykrywania

Aby wyszukać usunięte produkty pozyskane między dwiema datami:

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=ContentDate/Start gt 2021-09-01T00:00:00.000Z and ContentDate/End lt 2021-09-01T00:05:00.000Z

Zapytanie według kryteriów geograficznych

Aby wyszukać usunięte produkty przecinające określony wielokąt:

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=OData.CSC.Intersects(area=geography'SRID=4326;POLYGON ((-75.000244 -42.4521508418609, -75.000244 -43.4409190460844, -73.643585 -43.432873907284, -73.66513 -42.4443775132447, -75.000244 -42.4521508418609))') and ContentDate/Start gt 2021-01-01T00:00:00.000Z and ContentDate/End lt 2021-04-01T23:59:59.999Z

Zapytanie według atrybutów

Aby wyszukać produkty według atrybutów, konieczne jest zbudowanie filtra o określonej strukturze jaki zdefiniowano w linku

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=Attributes/OData.CSC.IntegerAttribute/any(att:att/Name eq 'orbitNumber' and att/OData.CSC.IntegerAttribute/Value eq 10844) and attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'orbitDirection' and att/OData.CSC.StringAttribute/Value eq 'ASCENDING')

Dodatkowe opcje

Dodatkowe opcje dla zapytania o usunięte produkty są następujące:

Opcja Orderby

Opcja Orderby działa w taki sam sposób, jak wyjaśniono powyżej w sekcji orderby.

W przypadku punktu końcowego OData DeletedProducts dopuszczalne argumenty dla tej opcji to:

  • ContentDate/Start, ContentDate/End

  • DeletionDate

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=contains(Name,'S1A_EW_GRD') and DeletionDate gt 2023-04-01T00:00:00.000Z and DeletionDate lt 2023-05-30T23:59:59.999Z&$orderby=DeletionDate desc

Opcja Expand

Opcja Expand umożliwia użytkownikom wyświetlenie pełnych metadanych każdego zwróconego wyniku.

Dopuszczalne argumenty dla tej opcji:

  • Attributes

Aby wyświetlić metadane wyników:

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=contains(Name,'S2A') and DeletionDate gt 2023-04-01T00:00:00.000Z and DeletionDate lt 2023-05-30T23:59:59.999Z&$expand=Attributes

Opcja Skip

Opcja Skip może być używana zgodnie z definicją w sekcji Opcja Skip powyżej.

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=contains(Name,'S2A') and ContentDate/Start ge 2021-04-01T00:00:00.000Z and ContentDate/Start le 2021-04-30T23:59:59.999Z&$skip=30

Opcja Top

Opcja top może być używana zgodnie z definicją w sekcji Opcja Top powyżej.

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=contains(Name,'S1A_EW_GRD') and ContentDate/Start ge 2021-09-01T00:00:00.000Z and ContentDate/Start le 2021-09-30T23:59:59.999Z&$top=40

Opcja Count

Opcja Count może być używana zgodnie z definicją w sekcji Opcja Count powyżej.

Żądanie HTTP

https://catalogue.nsiscloud.polsa.gov.pl/odata/v1/DeletedProducts?$filter=contains(Name,'S1A_EW_GRD') and DeletionDate gt 2023-04-01T00:00:00.000Z and DeletionDate lt 2023-05-30T23:59:59.999Z&$orderby=DeletionDate desc&$count=True

Co można zrobić dalej?

Aby dowiedzieć się, jak pobrać pojedynczy plik z produktu lub cały produkt jako archiwum ZIP, zapoznaj się z artykułem Użycie curl i wget do pobierania produktów EODATA z NSIS Cloud.