<commit_before>---
layout: post
title: Search hits API
excerpt: Querying search hits by look date 
---

The representation of all datasets follows the
[JSON-stat](http://json-stat.org/) standard.
The only exception is the ability to refer to dimension descriptions through
[JSONAPI](http://jsonapi.org/) `links` instead of `uri` attributes.

One example of such a dataset resource is the number of search hits by look date
(versus hits by departure date), whose URL is given by the `q_search_look`
relation type in the inventory of `analyses` given by the API entry point.

The `q_search_look` relation type expects the following query parameters:
* `origin`: 3-letter IATA code of the departure city
* `destination`: 3-letter IATA code of the arrival city
* `market`: 2-letter IATA country code of the point of sale
* `month`: month of look date formatted as YYYY-MM

Example:

    $ curl -v ".../search_look_hits?origin=NCE&destination=PAR&market=FR&month=2013-01" \
      -H 'Accept: application/json' \
      -H 'Authorization: Token <PASSWORD>'

    {
      "search_look_hits": {
        "dataset": {
          "value": [295137],
          "dimension": {
            "id": ["hits", "origin", "destination", "month"],
            "size": [1, 1, 1, 1],
            "role": {
              "geo": ["origin", "destination"],
              "time": ["month"],
              "metric": ["hits"]
            },
            "hits": {
              "category": { "unit": { "hits": { "type": "count" } } }
            },
            "origin": {
              "category": {
                "label": { "NCE": "Nice" },
                "long": { "NCE": 7.26608 },
                "lat": { "NCE": 43.70313 }
              },
              "links": {
                "dim": "https://..."
              }
            },
            "destination": {
              "category": {
                "label": { "PAR": "Paris" },
                "long": { "PAR": 2.3488 },
                "lat": { "PAR": 48.85341 }
              },
              "links": {
                "dim": "https://..."
              }
            },
            "month": { "category": { "index": { "2013-01": 0 } } }
          }
        }
      }
    }<commit_msg>Documentation of the complete search look hits resource.<commit_after>---
layout: post
title: Search hits API
excerpt: Querying search hits by look date 
---

The representation of all datasets follows the
[JSON-stat](http://json-stat.org/) standard.
The only exception is the ability to refer to dimension descriptions through
[JSONAPI](http://jsonapi.org/) `links` instead of `uri` attributes.

One example of such a resource is the number of search hits by look date
(versus hits by departure date), whose URL is given by the `q_search_look`
relation type in the inventory of `analyses` given by the API entry point.

The `q_search_look` relation type expects the following query parameters:
* `market`: 2-letter IATA country code of the point of sale
* `month`: month of look date formatted as YYYY-MM
* `origin`: 3-letter IATA code of the departure city (**optional**)
* `destination`: 3-letter IATA code of the arrival city (**optional**)

Different aggregation levels are returned depending on the presence of neither,
either or both of the origin and destination parameters.

Five datasets are represented by this resource:
* `total`: total number of hits.
* `top_onds`: top 50 *origin and destination* pairs of cities.
* `top_destinations`: top 50 destination cities.
* `advance_search`: distribution of look dates in weeks prior to departure.
* `duration`: distribution of stay durations in days.

Example:

    $ curl -v ".../search_look_hits?market=FR&month=2012-01&origin=NCE" \
      -H 'Accept: application/json' \
      -H 'Authorization: Token <PASSWORD>'

    {
      "search_look_hits": {
        "total": {
          "value": [4301888],
          "dimension": {
            "id": ["hit", "month", "origin"],
            "size": [1, 1, 1],
            "role": {
              "geo": ["origin"],
              "time": ["month"],
              "metric": ["hit"]
            },
            "hit": {
              "category": { "unit": { "hit": { "type": "count" } } }
            },
            "month": {
              "category": {
                "unit": { "month": { "type": "time" } },
                "index": { "2012-01": 0 }
              }
            },
            "origin": {
              "category": {
                "index": { "NCE": 0 },
                "label": { "NCE": "Nice" },
                "coordinates": { "NCE": [7.26608, 43.70313] }
              },
              "links": {
                "dim": "https://demo.travel-intelligence.com/api/v1/dimensions/city"
              }
            }
          }
        },
        "top_onds": {
          "value": [293860, 265520, 258844, 183935, 114853, ... ],
          "dimension": {
            "id": ["hit", "month", "origin_destination"],
            "size": [1, 1, 50],
            "role": {...},
            "hit": {...},
            "month": {...},
            "origin_destination": {
              "category": {
                "index": {
                  "NCE-NYC": 0,
                  "NCE-BKK": 1,
                  "NCE-PAR": 2,
                  "NCE-ASU": 3,
                  "NCE-KUL": 4,
                  ...
                },
                "label": {
                  "NCE-NYC": "Nice to New York City",
                  "NCE-BKK": "Nice to Bangkok",
                  "NCE-PAR": "Nice to Paris",
                  "NCE-ASU": "Nice to Asuncion / Aeropuerto",
                  "NCE-KUL": "Nice to Kuala Lumpur",
                  ...
                },
              }
            }
          }
        },
        "top_destinations": {
          "value": [293860, 265520, 258844, 183935, 114853, ... ],
          "dimension": {
            "id": ["hit", "month", "destination"],
            "size": [1, 1, 50],
            "role": {...},
            "hit": {...},
            "month": {...},
            "destination": {
              "category": {
                "index": {
                  "NYC": 0,
                  "BKK": 1,
                  "PAR": 2,
                  "ASU": 3,
                  "KUL": 4,
                  ...
                },
                "label": {
                  "NYC": "New York City",
                  "BKK": "Bangkok",
                  "PAR": "Paris",
                  "ASU": "Asuncion / Aeropuerto",
                  "KUL": "Kuala Lumpur",
                  ...
                },
                "coordinates": {
                  "NYC": [-73.97, 40.78],
                  "BKK": [100.50144, 13.75398],
                  "PAR": [2.3488, 48.85341],
                  "ASU": [-57.519133, -25.23985],
                  "KUL": [101.68653, 3.1412],
                  ...
                }
              },
              "links": {
                "dim": "https://demo.travel-intelligence.com/api/v1/dimensions/city"
              }
            }
          }
        },
        "advance_search": {
          "value": [409479, 465867, 313760, 264242, 270688, ... ],
          "dimension": {
            "id": ["hit", "month", "week"],
            "size": [1, 1, 52],
            "role": {...},
            "hit": {...},
            "month": {...},
            "week": {
              "category": {
                "unit": { "week": { "type": "duration" } },
                "index": {
                  "0": 0,
                  "1": 1,
                  "2": 2,
                  "3": 3,
                  "4": 4,
                  ...
                }
              }
            }
          }
        },
        "duration": {
          "value": [60872, 108948, 287783, 259665, 190597, ... ],
          "dimension": {
            "id": ["hit", "month", "day"],
            "size": [1, 1, 360],
            "role": {...},
            "hit": {...},
            "month": {...},
            "day": {
              "category": {
                "unit": { "day": { "type": "duration" } },
                "index": {
                  "0": 0,
                  "1": 1,
                  "2": 2,
                  "3": 3,
                  "4": 4,
                  ...
                }
              }
            }
          }
        }
      }
    }
{'fraction_non_alphanumeric': 0.16009615384615383, 'fraction_numerical': 0.03918269230769231, 'mean_word_length': 1.248918918918919, 'pattern_counts': {'":': 161, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '341183', 'n_tokens_mistral': 2678, 'n_tokens_neox': 2328, 'n_words': 650}