---
title: 'Availability search'
url: 'https://documentation.netstorming.net/api-reference/activities/availability-search'
markdown: 'https://documentation.netstorming.net/api-reference/activities/availability-search.md'
date: '2026-06-30'
description: 'Availability search Product: activity Type: availability Availability search allows the client to search all available activities on a requested location. Request Request fields: location: where the activity takes place name: name of the point (i.e. "Piazza Del Colosseo" or "Piazzale Roma"…'
taxonomy:
  category:
    - docs
---

# Availability search

[](#)  [ API reference ](https://documentation.netstorming.net/api-reference)     [ Activities ](https://documentation.netstorming.net/api-reference/activities)      Availability search    

#### Availability search

Product: **activity**
Type: **availability**

Availability search allows the client to search all available activities on a requested location.

##### Request

Request fields:

- **location**: where the activity takes place
- - **name**: name of the point (i.e. "Piazza Del Colosseo" or "Piazzale Roma")
- - **address**: precise address of the point (with street name and number, city, postal code)
- - **lat**: latitude of the point
- - **lng**: longitude of the point
- **startdate**: date when the activity is expected to start
- - **date**: date in format *YYYY-mm-dd*
- **paxes**
- - **adults\_number**: number of adults
- - **children\_number**: number of children
- - **children\_ages**: List of children's ages. Each age must be an integer separated by a hyphen (-).
- **activity\_language** (optional)
- - **value**: the desired language [ISO2](https://it.wikipedia.org/wiki/ISO_639-2) for the requested activity.
- **options**
- - **flex\_dates**: when set to 'true', includes search results and details for dates within a ±3 days window around the requesed startdate. When 'false', returns results strictly for the requested startdate.
- - **only\_bookable**: when set to 'true', filters the results to return only activities that are actually available for booking on the chosen startdate. When 'false', includes also un-available activities for informational purposes.
- **language** (optional): language used to provide info and descriptions. PLEASE NOTE: we do not guarantee to provide all texts translated into the requested language.
- **currency** (optional): currency [ISO](https://en.wikipedia.org/wiki/ISO_4217) code in which you want to receive prices. PLEASE NOTE: we do not support all the existing currencies, but we may add one if you need it and if agreed with TO.

Request example:

```
<envelope>
    <header>
        <actor>exampleactor</actor>
        <user>exampleuser</user>
        <password>*****</password>
        <version>1.7.0</version>
        <timestamp>20260512150441</timestamp>
    </header>
    <query type="availability" product="activity">
        <paxes adults_number="2" children_number="2" children_ages="5-8" />    
        <location name="Piazzale Roma" address="Piazzale Roma, Venezia, Venice, Italy" lat="45.43818842198814" lng="12.318325039604192" />
        <startdate date="2026-06-25"/>
        <activity_language value="it"/>
        <options flex_dates="true" only_bookable="false"/>
    </query>
</envelope>
```

##### Response

Response example:

```
<envelope>
    <header>
        <version port="22222" host="example.netstorming.net">1.7.0</version>
        <timestamp>20260512150541</timestamp>
    </header>
    <response type="availability" product="activity">
        <search number="activities.avl6a2bf9ea7090f" time_search="6.462" time_xml="0.075"/>
        <paxes adults_number="2" children_number="2" children_ages="5-8"/>
        <startdate date="2026-06-25"/>
        <location name="Venice" address="Piazzale Roma, Venezia, Venice, Italy" lat="45.438188421988" lng="12.318325039604"/>
        <agreements count="3">
            <agreement code="0x13d.155631.ODMxY2Zj.1" available="true" bookable="true" private="true" deadline="2026-06-24 00:00:00">
                <calendars> <!-- show below calendars example documentation -->
                    ...
                </calendars>
                <activity_info>  <!-- show below activity_info example documentation -->
                    ...
                </activity_info>
                <prices>
                    <nett amount="54.5" currency="USD"/>
                    <gross amount="56.5" currency="USD"/>
                </prices>
                <cancellation_policies>
                    <policy from="2026-06-24 00:00:00" percentage="100"/>
                </cancellation_policies>
                <remarks/>
            </agreement>
            <agreement code="0x0e8.E-E10-A0BCNO0033-33834358#TOUR.ODQxZGE5" available="true" bookable="true" private="false" deadline="2026-06-21 00:00:00">
                <calendars> <!-- show below calendars example documentation -->
                    ...
                </calendars>
                <activity_info>  <!-- show below activity_info example documentation -->
                    ...
                </activity_info>
                <prices>
                <nett amount="1113" currency="USD"/>
                <gross amount="1115" currency="USD"/>
                </prices>
                <cancellation_policies>
                    <policy from="2026-06-21 00:00:00" percentage="100"/>
                </cancellation_policies>
                <remarks/>
            </agreement>
            <agreement code="0x13d.30249.MTc4YTZk.0" available="true" bookable="false" private="unknown" deadline="2026-06-12 14:22:02">
                <calendars> <!-- show below calendars example documentation -->
                    ...
                </calendars>
                <activity_info>  <!-- show below activity_info example documentation -->
                    ...
                </activity_info>
                <prices>
                    <nett amount="146.5" currency="USD"/>
                    <gross amount="148.5" currency="USD"/>
                </prices>
                <cancellation_policies/>
                <remarks/>
            </agreement>
        </agreements>
    </response>
</envelope>

```

Response fields:

**paxes**, **startdate**, **location** are "echo" fields. They contains the data we parsed from your availability request.

**search@number** is a unique id of your availability search. You should treat it as a string and do not assume any maximum lenght. You'll need this ID to proceed with availability/booking flow.

Every **response/agreements/agreement** is an available solution for your request and contains all the info as described below:

- **@code**: unique agreement code
- **@available**: if true, agreement is immediately available. If false, the service is on request
- **@bookable**: if true, agreement is bookable. If false, the activity is available in ±3 days window around the requesed startdate.
- **@private**: if true, the activity is private. If false, the activity is shared. If "unknown" that the information is not specified.
- **@deadline**: dealine date for cancellation without penalties
- **calendars** [See examples](https://documentation.netstorming.net/examples/activity-calendars-examples)
- **activity\_info** [See example](https://documentation.netstorming.net/examples/activity-info-example)
- **prices**:
- - **nett**:
- - - **@amount**: nett amount
- - - **@currency**: nett currency
- - **gross**
- - - **@amount**: gross amount (=nett amount + client markup)
- - - **@currency**: gross currency
- **cancellation\_policies** (optional):
- - **policy**:
- - - **@from**: date in format "YYYY-mm-dd H:i:s"
- - - **@percentage**: number
- **remarks** (optional): contains additional information about the service that should be shown to the customer. May contain useful info like inclusions/exclusions details, pickup/dropoff details and so on
- - **remark@text**: additional information about the service
- **additional\_required\_info** (optional)
- - **required\_info**: contains the details of a required field. It can include child nodes representing the allowed values.
- - - **@name**: field name
- - - **@type**: field type
- - - **@allowCustomValue**: if true values outside the pre-defined list are allowed. If false (default) only the values provided in the child nodes are accepted.

 [ ](https://documentation.netstorming.net/api-reference/activities/booking-flow) [](https://documentation.netstorming.net/api-reference/activities/detailed-availability)

---

## Navigation

- Parent: [Activities](https://documentation.netstorming.net/api-reference/activities.md)
- Previous: [Booking flow](https://documentation.netstorming.net/api-reference/activities/booking-flow.md)
- Next: [Detailed availability](https://documentation.netstorming.net/api-reference/activities/detailed-availability.md)