@gojinko/api-client 2.20.0 → 2.22.0

package/public-api.yaml

@@ -1570,12 +1570,6 @@ components:
           type: string
         last_name:
           type: string
-    AnalysisType:
-      type: string
-      enum: [snapshot, trend]
-    TravelPeriod:
-      type: string
-      enum: [Summer, Winter, Christmas, Easter, Next30Days, Next90Days, Custom]
     TravelerType:
       type: string
       enum: [Solo, Couple, Group, Family]
@@ -1593,10 +1587,6 @@ components:
         share:
           type: number
           format: double
-        growth:
-          type: number
-          format: double
-          description: "Growth % in trend mode (analysis=trend); omitted in snapshot."
     MarketRow:
       type: object
       required: [market]
@@ -1608,10 +1598,6 @@ components:
         share:
           type: number
           format: double
-        growth:
-          type: number
-          format: double
-          description: "Growth % in trend mode (analysis=trend); omitted in snapshot."
     AudienceRow:
       type: object
       required: [audience]
@@ -1623,36 +1609,26 @@ components:
         share:
           type: number
           format: double
-        growth:
-          type: number
-          format: double
-          description: "Growth % in trend mode (analysis=trend); omitted in snapshot."
     DestinationResponse:
       type: object
-      required: [analysis_type, rows]
+      required: [rows]
       properties:
-        analysis_type:
-          $ref: "#/components/schemas/AnalysisType"
         rows:
           type: array
           items:
             $ref: "#/components/schemas/DestinationRow"
     MarketResponse:
       type: object
-      required: [analysis_type, rows]
+      required: [rows]
       properties:
-        analysis_type:
-          $ref: "#/components/schemas/AnalysisType"
         rows:
           type: array
           items:
             $ref: "#/components/schemas/MarketRow"
     AudienceResponse:
       type: object
-      required: [analysis_type, rows]
+      required: [rows]
       properties:
-        analysis_type:
-          $ref: "#/components/schemas/AnalysisType"
         rows:
           type: array
           items:
@@ -1660,8 +1636,8 @@ components:
     Granularity:
       type: string
       enum: [day, week, month]
-      description: "Bucket size for an evolution series: day (default), week, or month."
-    EvolutionPoint:
+      description: "Bucket size for a trend series: week (default), day, or month."
+    TrendPoint:
       type: object
       required: [date, value]
       properties:
@@ -1701,7 +1677,7 @@ components:
           type: number
           format: double
           example: 1890
-    EvolutionSeries:
+    TrendSeries:
       type: object
       required: [series]
       properties:
@@ -1720,10 +1696,10 @@ components:
         series:
           type: array
           items:
-            $ref: "#/components/schemas/EvolutionPoint"
+            $ref: "#/components/schemas/TrendPoint"
         summary:
           $ref: "#/components/schemas/SeriesSummary"
-    EvolutionResponse:
+    TrendResponse:
       type: object
       required: [granularity, from, to, series]
       properties:
@@ -1742,27 +1718,24 @@ components:
         series:
           type: array
           items:
-            $ref: "#/components/schemas/EvolutionSeries"
+            $ref: "#/components/schemas/TrendSeries"
   parameters:
-    analysis:
-      name: analysis
-      in: query
-      required: true
-      description: Analysis mode. `trend` is accepted but currently returns snapshot-shaped data.
-      schema:
-        $ref: "#/components/schemas/AnalysisType"
-    originMarket:
-      name: origin_market
+    origin:
+      name: origin
       in: query
       required: false
-      description: "Origin market filter as <Level>:<Code>, e.g. Country:US or City:NYC."
+      description: "Origin filter as <Level>:<Code>, e.g. Country:US or City:NYC, or 'global' for all origins."
       schema:
         type: string
-    destinationFilter:
-      name: destination
+    originCountry:
+      name: origin_country
       in: query
       required: false
-      description: "Optional destination filter as <Level>:<Code>, e.g. Country:TH."
+      description:
+        "Origin country to rank cities within, as a Country selector Country:<code>
+        (e.g. Country:US). Market rankings only, and allowed ONLY together with
+        level=city: it scopes the ranked origin markets to a single country so that
+        country's cities are ranked. Must be a country — a City selector is rejected."
       schema:
         type: string
     destinationRequired:
@@ -1772,18 +1745,25 @@ components:
       description: "Destination as <Level>:<Code>, e.g. Country:TH. Required for this endpoint."
       schema:
         type: string
-    travelPeriod:
-      name: travel_period
+    destinationCountry:
+      name: destination_country
       in: query
       required: false
-      description: Named departure window (defaults to Next90Days server-side).
+      description:
+        "Destination country to rank cities within, as a Country selector Country:<code>
+        (e.g. Country:FR). Destination rankings only, and allowed ONLY together with
+        level=city: it scopes the ranked destinations to a single country so that
+        country's cities are ranked. Must be a country — a City selector is rejected."
       schema:
-        $ref: "#/components/schemas/TravelPeriod"
+        type: string
     departureDateFrom:
       name: departure_date_from
       in: query
       required: false
-      description: "Start of departure window (YYYY-MM-DD). Required when travel_period=Custom."
+      description:
+        "Start of the departure window (YYYY-MM-DD). Supply together with
+        departure_date_to; omit both for no departure-date filter (all departure
+        dates)."
       schema:
         type: string
         format: date
@@ -1791,7 +1771,10 @@ components:
       name: departure_date_to
       in: query
       required: false
-      description: "End of departure window (YYYY-MM-DD). Required when travel_period=Custom."
+      description:
+        "End of the departure window (YYYY-MM-DD). Supply together with
+        departure_date_from; omit both for no departure-date filter (all
+        departure dates)."
       schema:
         type: string
         format: date
@@ -1845,20 +1828,11 @@ components:
       name: snapshot_window_days
       in: query
       required: false
-      description: "Snapshot mode only: number of most-recent days of search activity aggregated into the demand level (min 2, default 7, max 90 — a 1-day window is the current day, whose data is incomplete; the cube retains 90 days). Rejected when analysis=trend."
+      description: "Number of most-recent days of search activity aggregated into the demand level (min 2, default 7, max 90 — a 1-day window is the current day, whose data is incomplete; the cube retains 90 days)."
       schema:
         type: integer
         minimum: 2
         maximum: 90
-    trendWindowDays:
-      name: trend_window_days
-      in: query
-      required: false
-      description: "Trend mode only: size in days of each of the two adjacent windows compared for growth (min 2, default 7, max 45 — a 1-day window's recent period is the current day, whose data is incomplete; a trend spans 2x the window within the cube's 90-day retention). Rejected when analysis=snapshot."
-      schema:
-        type: integer
-        minimum: 2
-        maximum: 45
     limit:
       name: limit
       in: query
@@ -1885,27 +1859,26 @@ components:
       schema:
         type: string
         minLength: 1
-    evolutionWindowDays:
-      name: trend_window_days
+    trendWindow:
+      name: trend_window
       in: query
       required: false
-      description: "Size of the evolution window in days (min 2, default 7, max 45). The series spans the last N complete days ending yesterday; the current day is excluded as incomplete."
+      description: "Number of buckets N in the chosen granularity's own unit (min 2; max depends on granularity: day <= 60, week <= 52, month <= 12; default 12 applied server-side). The series spans the last N complete buckets, excluding the in-progress one."
       schema:
         type: integer
         minimum: 2
-        maximum: 45
     granularity:
       name: granularity
       in: query
       required: false
-      description: "Bucket size for the returned series: day (default), week, or month."
+      description: "Bucket size for the returned series: week (default), day, or month."
       schema:
         $ref: "#/components/schemas/Granularity"
-    evolutionLimit:
+    trendLimit:
       name: limit
       in: query
       required: false
-      description: "Evolution endpoints: maximum number of series (top-N keys). Default 10, max 50."
+      description: "Trend endpoints: maximum number of series (top-N keys). Default 10, max 50."
       schema:
         type: integer
         minimum: 1
@@ -1918,16 +1891,14 @@ paths:
         - demand
       summary: Top destinations by search demand
       description: >-
-        Most-searched destinations by de-sampled request share. `destination` is optional
-        (omit to rank all destinations); set `origin_market` to scope to one source market.
+        Most-searched destinations by de-sampled request share. Set `origin` to
+        scope to one source market. Optional `destination_country` (a Country selector,
+        allowed only with `level=city`) narrows the ranking to that country's destination cities.
       security:
         - ApiKeyAuth: []
         - BearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/analysis"
-        - $ref: "#/components/parameters/originMarket"
-        - $ref: "#/components/parameters/destinationFilter"
-        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/origin"
         - $ref: "#/components/parameters/departureDateFrom"
         - $ref: "#/components/parameters/departureDateTo"
         - $ref: "#/components/parameters/travelerType"
@@ -1937,8 +1908,8 @@ paths:
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
         - $ref: "#/components/parameters/snapshotWindowDays"
-        - $ref: "#/components/parameters/trendWindowDays"
         - $ref: "#/components/parameters/limit"
+        - $ref: "#/components/parameters/destinationCountry"
       responses:
         "200":
           description: OK
@@ -1968,10 +1939,7 @@ paths:
         - ApiKeyAuth: []
         - BearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/analysis"
         - $ref: "#/components/parameters/destinationRequired"
-        - $ref: "#/components/parameters/originMarket"
-        - $ref: "#/components/parameters/travelPeriod"
         - $ref: "#/components/parameters/departureDateFrom"
         - $ref: "#/components/parameters/departureDateTo"
         - $ref: "#/components/parameters/travelerType"
@@ -1981,8 +1949,8 @@ paths:
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
         - $ref: "#/components/parameters/snapshotWindowDays"
-        - $ref: "#/components/parameters/trendWindowDays"
         - $ref: "#/components/parameters/limit"
+        - $ref: "#/components/parameters/originCountry"
       responses:
         "200":
           description: OK
@@ -2014,10 +1982,8 @@ paths:
         - ApiKeyAuth: []
         - BearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/analysis"
         - $ref: "#/components/parameters/destinationRequired"
-        - $ref: "#/components/parameters/originMarket"
-        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/origin"
         - $ref: "#/components/parameters/departureDateFrom"
         - $ref: "#/components/parameters/departureDateTo"
         - $ref: "#/components/parameters/tripType"
@@ -2026,7 +1992,6 @@ paths:
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
         - $ref: "#/components/parameters/snapshotWindowDays"
-        - $ref: "#/components/parameters/trendWindowDays"
         - $ref: "#/components/parameters/limit"
       responses:
         "200":
@@ -2047,13 +2012,13 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /v1/evolution:
+  /v1/trend:
     get:
       tags:
         - demand
-      summary: Daily demand time series for explicit origin/destination pairs
+      summary: Demand time series for explicit origin/destination pairs
       description: >-
-        Deep dive: returns one daily de-sampled search-volume series per
+        Deep dive: returns one de-sampled search-volume series per
         (origin, destination) pair. v1 allows a list on only one side — a single
         origin with many destinations, or many origins with a single destination.
       security:
@@ -2062,7 +2027,6 @@ paths:
       parameters:
         - $ref: "#/components/parameters/origins"
         - $ref: "#/components/parameters/destinations"
-        - $ref: "#/components/parameters/travelPeriod"
         - $ref: "#/components/parameters/departureDateFrom"
         - $ref: "#/components/parameters/departureDateTo"
         - $ref: "#/components/parameters/travelerType"
@@ -2071,7 +2035,7 @@ paths:
         - $ref: "#/components/parameters/tripDurationMax"
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
-        - $ref: "#/components/parameters/evolutionWindowDays"
+        - $ref: "#/components/parameters/trendWindow"
         - $ref: "#/components/parameters/granularity"
       responses:
         "200":
@@ -2079,7 +2043,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/EvolutionResponse"
+                $ref: "#/components/schemas/TrendResponse"
         "401":
           description: Authentication required
           content:
@@ -2092,21 +2056,21 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /v1/destination/evolution:
+  /v1/destination/trend:
     get:
       tags:
         - demand
-      summary: Daily demand time series for the top-N destinations
+      summary: Demand time series for the top-N destinations
       description: >-
-        Ranks destinations (optionally reachable from origin_market) by
-        within-window growth, then returns each top-N destination's daily series.
+        Ranks destinations (optionally reachable from origin) by
+        within-window growth, then returns each top-N destination's series.
+        Optional destination_country (a Country selector, allowed only with
+        level=city) narrows the ranking to that country's destination cities.
       security:
         - ApiKeyAuth: []
         - BearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/originMarket"
-        - $ref: "#/components/parameters/destinationFilter"
-        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/origin"
         - $ref: "#/components/parameters/departureDateFrom"
         - $ref: "#/components/parameters/departureDateTo"
         - $ref: "#/components/parameters/travelerType"
@@ -2115,16 +2079,17 @@ paths:
         - $ref: "#/components/parameters/tripDurationMax"
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
-        - $ref: "#/components/parameters/evolutionWindowDays"
+        - $ref: "#/components/parameters/trendWindow"
         - $ref: "#/components/parameters/granularity"
-        - $ref: "#/components/parameters/evolutionLimit"
+        - $ref: "#/components/parameters/trendLimit"
+        - $ref: "#/components/parameters/destinationCountry"
       responses:
         "200":
           description: Top-N destination time series
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/EvolutionResponse"
+                $ref: "#/components/schemas/TrendResponse"
         "401":
           description: Authentication required
           content:
@@ -2137,21 +2102,19 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /v1/market/evolution:
+  /v1/market/trend:
     get:
       tags:
         - demand
-      summary: Daily demand time series for the top-N source markets
+      summary: Demand time series for the top-N source markets
       description: >-
         Ranks source markets for a destination by within-window growth, then
-        returns each top-N market's daily series. `destination` is required.
+        returns each top-N market's series. `destination` is required.
       security:
         - ApiKeyAuth: []
         - BearerAuth: []
       parameters:
         - $ref: "#/components/parameters/destinationRequired"
-        - $ref: "#/components/parameters/originMarket"
-        - $ref: "#/components/parameters/travelPeriod"
         - $ref: "#/components/parameters/departureDateFrom"
         - $ref: "#/components/parameters/departureDateTo"
         - $ref: "#/components/parameters/travelerType"
@@ -2160,16 +2123,17 @@ paths:
         - $ref: "#/components/parameters/tripDurationMax"
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
-        - $ref: "#/components/parameters/evolutionWindowDays"
+        - $ref: "#/components/parameters/trendWindow"
         - $ref: "#/components/parameters/granularity"
-        - $ref: "#/components/parameters/evolutionLimit"
+        - $ref: "#/components/parameters/trendLimit"
+        - $ref: "#/components/parameters/originCountry"
       responses:
         "200":
           description: Top-N market time series
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/EvolutionResponse"
+                $ref: "#/components/schemas/TrendResponse"
         "401":
           description: Authentication required
           content:
@@ -2182,13 +2146,13 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /v1/audience/evolution:
+  /v1/audience/trend:
     get:
       tags:
         - demand
-      summary: Daily demand time series for the traveler-type mix
+      summary: Demand time series for the traveler-type mix
       description: >-
-        Returns a daily series per traveler-type segment (Solo / Couple / Family /
+        Returns a series per traveler-type segment (Solo / Couple / Family /
         Group) of demand for a destination. `destination` is required;
         `traveler_type` is not a filter here — this endpoint buckets by it.
       security:
@@ -2196,8 +2160,7 @@ paths:
         - BearerAuth: []
       parameters:
         - $ref: "#/components/parameters/destinationRequired"
-        - $ref: "#/components/parameters/originMarket"
-        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/origin"
         - $ref: "#/components/parameters/departureDateFrom"
         - $ref: "#/components/parameters/departureDateTo"
         - $ref: "#/components/parameters/tripType"
@@ -2205,16 +2168,16 @@ paths:
         - $ref: "#/components/parameters/tripDurationMax"
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
-        - $ref: "#/components/parameters/evolutionWindowDays"
+        - $ref: "#/components/parameters/trendWindow"
         - $ref: "#/components/parameters/granularity"
-        - $ref: "#/components/parameters/evolutionLimit"
+        - $ref: "#/components/parameters/trendLimit"
       responses:
         "200":
           description: Per-segment time series
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/EvolutionResponse"
+                $ref: "#/components/schemas/TrendResponse"
         "401":
           description: Authentication required
           content: