Merge branch 'main' into uitpas/online-uitpas

# Conflicts:
#	projects/uitpas/reference/uitpas.json

landingpage.md

@@ -10,20 +10,24 @@ Welcome to publiq's API documentation portal!
 
 Here you can find how-to guides, API specifications and other tools to help you integrate with our products like UiTdatabank, UiTPAS and museumPASSmusées.
 
-To learn more about publiq and our products, see <https://www.publiq.be>
+To learn more about publiq and our products, see <https://www.publiq.be/nl/projecten/publiq-platform>
 
 ## Getting started
 
 If you want to build an API integration:
 
 1. Check out the introduction pages of the [UiTdatabank](https://docs.publiq.be/docs/uitdatabank/introduction), [UiTPAS](https://docs.publiq.be/docs/uitpas/introduction) and [museumPASSmusées](https://docs.publiq.be/docs/museumpassmusees/introduction) APIs to see which ones you'd like to integrate with.
-2. [Register your project](https://docs.publiq.be/docs/authentication/requesting-credentials) to receive client credentials to authenticate with.
+2. [Register your integration](https://platform.publiq.be) to receive client credentials to authenticate with.
 3. [Learn about our different authentication methods](https://docs.publiq.be/docs/authentication/methods/overview) and pick the one best suited to your situation.
 4. Browse the how-to guides and API specifications of the product that you're integrating with. Every API also has an **OpenAPI file** and a **Postman collection** to get you started quickly.
 5. Get building!
 
 Alternatively, check out our flexible plug and play [Widgets](https://docs.publiq.be/docs/widgets/inleiding) to easily add an online calendar to your website without building an API integration.
 
+<!-- focus: false -->
+
+[![Add your search API integration](https://raw.githubusercontent.com/cultuurnet/apidocs/main/assets/add-your-integration.svg)](https://platform.publiq.be)
+
 ## Versioning strategy
 
 At publiq, we aim for API evolution over versioning.

projects/authentication/docs/requesting-credentials.md

@@ -1,28 +1,19 @@
 # Requesting client credentials
 
-Before you can start making authenticated API requests, you need to register your integration with us so we can provide you with the necessary credentials.
+## UiTPAS API & UiTdatabank APIs
 
-While we are working on a new self-service platform where you will be able to register your project for any API integration and automatically recieve client credentials in the future, the method to request your credentials currently varies per API as it is handled by multiple teams.
+Before you can start making authenticated API requests to UiTPAS and/or UiTdatabank, you need to register your integration on our self-service platform [publiq platform](https://platform.publiq.be). In the registration process you'll need to pick the API you want to use:
 
-> You may access multiple APIs with the same client credentials, but your project needs to be configured correctly on our side to have permission to access all the APIs you need. So if you require access to multiple APIs, make sure to mention this when requesting the credentials so we can give your client sufficient access permissions.
+* [UiTPAS API](https://docs.publiq.be/docs/uitpas/introduction)
+* [UiTdatabank Entry API](https://docs.publiq.be/docs/uitdatabank/entry-api/introduction)
+* [UiTdatabank Search API](https://docs.publiq.be/docs/uitdatabank/search-api/introduction)
 
-## UiTPAS
+Note that the UiTPAS API will also grant you access to the UiTdatabank Entry API.
 
-To use [UiTPAS API v4](https://docs.publiq.be/docs/uitpas/introduction), see its [quickstart guide](https://docs.publiq.be/docs/uitpas/d0748f47a3dba-quick-start) to request a client id and client secret via the linked Google Form.
+Registration and access to our test environment is free. After registration you'll immediately get your test credentials.
 
-## UiTdatabank
+[![Add your entry API integration](https://raw.githubusercontent.com/cultuurnet/apidocs/main/assets/add-your-integration.svg)](https://platform.publiq.be)
 
-UiTdatabank APIs historically use a custom authentication method based on API keys instead of client ids and secrets.
+## museumPASSmusées Partner API
 
-Support for the standardized authentication methods documented in this space has been implemented, but new client ids and secrets are only provided to a select few partners that are trying out these new authentication methods in UiTdatabank. In the future this will be opened up to all integrators.
-
-Want to start integrating with UiTdatabank right now? There are three options:
-
-1. If you need to integrate with both the **UiTPAS API and UiTdatabank API(s)**, you can follow the procedure of requesting credentials for the UiTPAS API and mention that you also require access to the UiTdatabank APIs. We will then provide you with a set of credentials that can access both.
-2. **Or**, if you only need to integrate with the UiTdatabank API(s) you can register your integration at [publiq platform](https://platform.publiq.be) to automatically get a test **client id** and **secret**.
-
-Aside from the authentication method all API operations on the UiTdatabank APIs work exactly the same whether you have a client id and secret, or an API key.
-
-## museumPASSmusées
-
-Access to the [museumPASSmusées Partner API](https://docs.publiq.be/docs/museumpassmusees/introduction) is only provided to very specific partners for now as the primary use case at the moment is registering museum visits via a card reader. To request your credentials, please contact <[email protected]>.
+The [museumPASSmusées Partner API](https://docs.publiq.be/docs/museumpassmusees/introduction) is currently not included on our self-service platforma, as it is only provided to very specific partners for now as the primary use case at the moment is registering museum visits via a card reader. To request your credentials, please contact <[email protected]>.

projects/release-notes/docs/uitdatabank/2024.md

@@ -4,17 +4,18 @@
 
 🛠 **Improvements**
 
-User interface: 
+User interface:
+
 * it is now possible to save executed searches on an existing saved search, besides creating a new saved search.
 * executed searches are now added as an URL parameter in your browser URL, making it possible to share a direct URL to an executed search, e.g. an URL to all online events with at least one videolink: `https://www.uitdatabank.be/search?query=attendanceMode%3Aonline+AND+videosCount%3A1`.
 * the query builder now allows you to start from an executed search and edit the search.
 
-
 ## February 15
 
 ✨ **New features**
 
 For every event, place & organizer created in UiTdatabank we now store its `completeness`. The completeness score is a number between 0 and 100 that indicates how complete the information of an event, place or organizer is.
+
 * Using the [avanced query field completeness](https://docs.publiq.be/docs/uitdatabank/search-api%2Fadvanced-queries#completeness) you can filter events, places and organizers by their completeness score.
 * Using the [sort parameter completeness](https://docs.publiq.be/docs/uitdatabank/search-api%2Fsorting#completeness) you can now sort data you retrieve from the API by its completeness.
 

projects/release-notes/docs/widgets/2024.md

@@ -10,7 +10,6 @@
 * Points required for an UiTPAS reward are now also displayed in the UiTPAS reward section on the detail page.
 * Reservation e-mail on the detail page is now a clickable mailto link.
 
-
 ## January 16
 
 ✨ **New features**

projects/uitdatabank/docs/entry-api/authentication.md

@@ -2,7 +2,11 @@
 
 ## Requesting credentials
 
-See the [requesting client credentials](https://docs.publiq.be/docs/authentication/requesting-credentials) page in the general authentication documentation.
+You can easily get free test credentials in publiq platform, our self-service portal:
+
+[![Add your entry API integration](https://raw.githubusercontent.com/cultuurnet/apidocs/main/assets/add-your-integration.svg)](https://platform.publiq.be)
+
+After registering your integration on publiq platform you'll immediately get client credentials that grant you access to our test environment.
 
 ## OAuth2 tokens (using a client id & secret)
 

projects/uitdatabank/docs/entry-api/events/create-school.md

@@ -15,7 +15,7 @@ Creating a school event is very similar to [creating a regular new event](./crea
 
 > There is also a user interface available to enter school events, on <https://www.uitdatabank.be>. We recommend using this interface, instead of building an API integration, if you only organize a limited number of school events per year.
 >
-> For questions about school events, please contact <content.cultuurkuur@publiq.be>.
+> For questions about school events, please contact <vragen@cultuurkuur.be>.
 
 ## Required permissions
 

projects/uitdatabank/docs/entry-api/events/create.md

@@ -332,7 +332,7 @@ Read our guide about [calendar info](../shared/calendar-info.md) to learn more.
 
 While you can create a new event using just the properties described above, an event can have a lot more properties like a [description](../shared/description.md), [booking- and contact info](../shared/booking-and-contact-info.md), [images](../shared/images.md), [price info](../shared/price-info.md) and so on. These are useful to make your event more attractive to potential audiences and may be included in the same request when creating a new event.
 
-Note that most integrations will also need to provide these properties to successfully [pass the content quality check](../requirements-before-going-live.md) and obtain credentials for the Entry API production environment.
+Note that most integrations will also need to provide these properties to successfully [pass the content quality check](../getting-started.md) and obtain credentials for the Entry API production environment.
 
 You can learn more about these properties under the "Shared properties" section in the menu, or by browsing the complete [event model](../../../models/event-with-read-example.json).
 

projects/uitdatabank/docs/entry-api/requirements-before-going-live.md → projects/uitdatabank/docs/entry-api/getting-started.md

@@ -1,25 +1,25 @@
----
-stoplight-id: 73ef6e15ee3ec
----
-
-# Requirements before going live
+# Getting started
 
 For the integration with the UiTdatabank Entry API, there is a flow in which you first obtain access to our the test environment.
 Access to the production environment is given after your integration on the test environment has been successfully validated by publiq vzw.
 
 On this page we describe how this flow works and how you can ensure that you gain access to the production environment as quickly as possible.
 
-> Make sure you read this guide before you start developing on our test environment.
+> There are a few requirements that must be met to go live. Make sure you read this guide before you start developing on our test environment.
 
 ## 1. Start on the test environment
 
-You can easily apply for free test credentials. All information about how to request these can be found [here](https://docs.publiq.be/docs/authentication/requesting-credentials#uitdatabank).
+You can easily get free test credentials in our API portal:
+
+<!-- focus: false -->
+
+[![Add your entry API integration](https://raw.githubusercontent.com/cultuurnet/apidocs/main/assets/add-your-integration.svg)](https://platform.publiq.be)
 
 Once you've obtained your personal test credentials you can start with the development of your integration with the UiTdatabank Entry API on our test environment.
 
 ## 2. Validation by publiq vzw
 
-As soon as you have finished developing your integration with the Entry API, you send a minimum of 5 of events to our test environment. [Contact us](https://docs.publiq.be/#contact-us) with the email subject "content check". In the email you give us the identifiers of the created test events. We will then validate your integration as soon as possible.
+As soon as you have finished developing your integration with the Entry API, you can request the activation of your integration through our [API portal](https://platform.publiq.be). When doing so, you also send a minimum of 5 of events to our test environment. [Contact us](https://docs.publiq.be/#contact-us) with the email subject "content check". In the email you give us the identifiers of the created test events. We will then validate your integration as soon as possible.
 
 In this validation process we assess the integration in two manners:
 
@@ -55,4 +55,4 @@ When the created content & integration meets the listed conditions, we will imme
 
 ## 3. Switch to the production environment
 
-After a successful validation you will receive the credentials to connect to the production environment.
+After a successful validation you will automatically receive your production credentials in our [API portal](https://platform.publiq.be).

projects/uitdatabank/docs/entry-api/places/create.md

@@ -305,7 +305,7 @@ Read our guide about [calendar info](../shared/calendar-info.md) to learn more.
 
 While you can create a new place using just the properties described above, a place can have a lot more properties like a [description](../shared/description.md), [booking- and contact info](../shared/booking-and-contact-info.md), [images](../shared/images.md), [price info](../shared/price-info.md) and so on. These are useful to make your place more attractive to potential audiences and may be included in the same request when creating a new place.
 
-Note that most integrations will also need to provide these properties to successfully [pass the content quality check](../requirements-before-going-live.md) and obtain credentials for the Entry API production environment.
+Note that most integrations will also need to provide these properties to successfully [pass the content quality check](../getting-started.md) and obtain credentials for the Entry API production environment.
 
 You can learn more about these properties under the "Shared properties" section in the menu, or by browsing the complete [place model](../../../models/place-with-read-example.json).
 

projects/uitdatabank/docs/entry-api/shared/labels.md

@@ -60,7 +60,7 @@ Alternatively, you can set a label using one of these endpoints:
 To remove a label **when updating an event/place/organizer in its entirety**, you can simply leave out the specific `label`.
 
 <!-- theme: danger -->
->
+
 > Exception: some existing labels or hiddenLabels may be kept on the event, even if they are not included in the update request. For example, if they were added via the UiTdatabank UI, or if the client or user making the request does not have sufficient permission to remove some specific labels.
 
 Alternatively, you can delete a label using one of these endpoints:

projects/uitdatabank/docs/search-api/advanced/advanced-queries.md

@@ -288,9 +288,11 @@ GET /organizers/?q=completedLanguages:en
 ```
 
 ### completeness
+
 <!-- theme: info -->
 
 > #### New functionality 🚧
+>
 > `completeness` is a new parameter that is still under construction. At the moment the completeness is only calculated for events, places and organizers created after February 15, 2024.
 
 With the `completeness` field you can filter events, places and organizers by their completeness score. The completeness score is a number between 0 and 100 that indicates how complete the information of an event, place or organizer is.

projects/uitdatabank/docs/search-api/authentication.md

@@ -2,7 +2,11 @@
 
 ## Requesting credentials
 
-See the [requesting client credentials](https://docs.publiq.be/docs/authentication/requesting-credentials) page in the general authentication documentation.
+You can easily get free test credentials in publiq platform, our self-service portal:
+
+[![Add your entry API integration](https://raw.githubusercontent.com/cultuurnet/apidocs/main/assets/add-your-integration.svg)](https://platform.publiq.be)
+
+After registering your integration on publiq platform you'll immediately get client credentials that grant you access to our test environment.
 
 ## Tokens
 
@@ -59,7 +63,7 @@ More info about client identification can be found [in the general authenticatio
 
 ## API key
 
-Alternatively, if you registered your integration with publiq before or in the beginning of 2023 you will have received an API key instead of a client id.
+Alternatively, if you registered your integration with publiq before 2024 you will have received an API key instead of a client id.
 
 You can use your API key by adding an `x-api-key` header to your requests, for example:
 
@@ -92,7 +96,7 @@ Host: https://search-test.uitdatabank.be
 
 API key authentication will be supported for the foreseeable future on Search API. However, if you already want to make your integration as future-proof as possible you can easily switch from API key authentication to client identification.
 
-In the near future you will be able to request a client id for your existing integration on our self-service portal.
+On our [self-service portal](https://platform.publiq.be) you are able to request a client id for your existing integration.
 
 When you receive your new client id, you can update your application to include the client id in your API requests as described above using an `x-client-id` header instead of an `x-api-key` header, or a `clientId` query parameter instead of an `apiKey` query parameter.
 

projects/uitdatabank/docs/search-api/filters/booking-availability.md

@@ -1,3 +1,36 @@
 # Booking Availability
 
-coming soon.
+All events and places created in UiTdatabank have a `bookingAvailability` property. The bookingAvailability indicates whether there are still tickets or seats available for an event.
+
+> The bookingAvailability only indicates whether there are still tickets or seats available for an event. It does not provide information about any cancellations or date changes, which are instead indicated by the `status`.
+
+## Using the bookingAvailability parameter
+
+**Applicable on endpoints**
+
+`/events` `/places` `/offers`
+
+**Possible values**
+
+* `Available`: there are still tickets or seats left for the event, or the capacity for the event is unlimited.
+* `Unavailable`: the event is sold out or fully booked.
+
+**Examples**
+
+Search for all events that still have available tickets or open spots (URL parameter):
+
+```https
+GET /events/?bookingAvailability=Available
+```
+
+Search for all events that are sold out or fully booked (advanced query parameter):
+
+```https
+GET /events/?q=status:Unavailable
+```
+
+Search for all events that are not sold out or fully booked, and happen as plannend (advanced query parameters):
+
+```https
+GET /events/?q=bookingAvailability:Available AND status:Available  
+```

projects/uitdatabank/docs/search-api/filters/default-filters.md

@@ -66,7 +66,7 @@ GET /offers/?workflowStatus=*&addressCountry=*&audienceType=*
 
 ## Disable all filters at once
 
-In order to disable all filters at once you can set the `disableDefaultFilters` parameter to `true`. 
+In order to disable all filters at once you can set the `disableDefaultFilters` parameter to `true`.
 
 ```
 GET /offers/?disableDefaultFilters=true

projects/uitdatabank/docs/search-api/filters/status.md

@@ -1,3 +1,53 @@
-# status
+# Status
 
-coming soon.
+All events and places created in UiTdatabank have a `status` property. The status indicates whether
+
+* an event is still happening as plannend or not
+* a place is still open for visits or not
+
+> The status only indicates whether an event or place is proceeding as planned or is currently open. It does not provide information about the availability of tickets or spots, which is instead indicated by the `booking-availability`.
+
+## Using the status parameter
+
+You can use the `status` for filtering out items that are still available for visits or not. You can use the status filter as:
+
+* an url parameter (e.g. `status=available`)
+* an advanced query parameter (e.g. `status:avaialble`)
+
+**Applicable on endpoints**
+
+`/events` `/places` `/offers`
+
+**Possible values**
+
+Events:
+
+* `available`: the event takes place as planned This is the default value when no status for the event or subEvent is included.
+* `temporarilyUnavailable`: the event has been postponed to a later date yet to be determined.
+* `unavailable`: the event has been cancelled.
+
+Places:
+
+* `available`: the place is 'open' and can be visited during opening hours. This is the default value when no status for the place is included.
+* `temporarilyUnavailable`: the place is temporarily closed (due to renovations for example).
+* `unavailable`: the place still exists (physically), but is permanently closed.
+
+**Examples**
+
+Search for all events that take places as planned (URL parameter):
+
+```https
+GET /events/?status=Available
+```
+
+Search for all places that are permanently closed (advanced query parameter):
+
+```https
+GET /places/?q=status:Unavailable
+```
+
+Search for all events that are available in a given date range (advanced query parameters):
+
+```https
+GET /events/?q=status:Unavailable AND dateRange:[2025-05-01T00\:00\:00%2B01\:00 TO 2025-06-31T23\:59\:59%2B01\:00]
+```