docs/api.md

   1 ---
   2 layout: page
   3 permalink: /docs/api/
   4 redirect_from:
   5   - /api/
   6   - /docs/
   7 ---
   8 # JSON API Documentation
   9
  10 ## Metadata
  11
  12 ### List metadata for all {{ site.taps.core.name }} formulae or {{ site.taps.cask.name }} casks
  13
  14 List the `brew info --json` output for all current {{ site.taps.core.fullname }} formulae or {{ site.taps.cask.fullname }} casks.
  15
  16 ```console
  17 curl https://formulae.brew.sh/api/formula.json
  18 curl https://formulae.brew.sh/api/cask.json
  19 ```
  20
  21 **[Response](https://formulae.brew.sh/api/formula.json):**
  22
  23 {% include api-samples/formula.md %}
  24
  25 ### Get formula metadata for a {{ site.taps.core.name }} formula
  26
  27 Get the `brew info --json --formula <formula>` output for a single, current {{ site.taps.core.fullname }} formula with extra keys containing analytics data and generation date.
  28
  29 ```console
  30 curl https://formulae.brew.sh/api/formula/${FORMULA}.json
  31 ```
  32
  33 **Variables:**
  34
  35 - `${FORMULA}`: the name of the formula, e.g. `wget`
  36
  37 **[Response](https://formulae.brew.sh/api/formula/wget.json):**
  38
  39 {% include api-samples/formula_wget.md %}
  40
  41 ### Get cask metadata for a {{ site.taps.cask.name }} cask
  42
  43 Get the `brew info --json=v2 --cask <cask>` JSON output for a single, current {{ site.taps.cask.fullname }} cask with extra keys containing analytics data and generation date.
  44
  45 ```console
  46 curl https://formulae.brew.sh/api/cask/${CASK}.json
  47 ```
  48
  49 **Variables:**
  50
  51 - `${CASK}`: the name of the cask, e.g. `docker`
  52
  53 **[Response](https://formulae.brew.sh/api/cask/docker.json):**
  54
  55 {% include api-samples/cask_docker.md %}
  56
  57 ## Analytics
  58
  59 ### List one category of analytics events
  60
  61 List all analytics events for a specified category over a number of days, ordered by event frequency count. This is the data source for `brew info --analytics`.
  62
  63 ```console
  64 curl https://formulae.brew.sh/api/analytics/${CATEGORY}/${DAYS}.json
  65 ```
  66
  67 **Variables:**
  68
  69 - `${CATEGORY}`: the analytics event category, i.e.
  70   - `install`: the installation of all formulae
  71   - `install-on-request`: the requested installation of all formulae (i.e. not as a dependency of other formulae)
  72   - `build-error`: the installation failure of all formulae
  73 - `${DAYS}`: the number of days of analytics events, i.e.
  74   - `30d`: 30 days
  75   - `90d`: 90 days
  76   - `365d`: 365 days
  77
  78 **[Response](https://formulae.brew.sh/api/analytics/install/30d.json):**
  79
  80 {% include api-samples/analytics_install_30d.md %}
  81
  82 ### List analytics events for all {{ site.taps.core.name }} formulae
  83
  84 List all the {{ site.taps.core.fullname }} formulae's analytics events for a specified category over a number of days, grouped by formula name. This is the data source for `brew info --analytics --formula <formula>`.
  85
  86 ```console
  87 curl https://formulae.brew.sh/api/analytics/${CATEGORY}/homebrew-core/${DAYS}.json
  88 ```
  89
  90 **Variables:**
  91
  92 - `${CATEGORY}`: the analytics event category, i.e.
  93   - `install`: the installation of all {{ site.taps.core.repository }} formulae
  94   - `install-on-request`: the requested installation of all {{ site.taps.core.repository }} formulae (i.e. not as a dependency of other formulae)
  95   - `build-error`: the installation failure of all {{ site.taps.core.repository }} formulae
  96     - only `${DAYS}: 30d` (30 days) is available
  97 - `${DAYS}`: the number of days of analytics events, i.e.
  98   - `30d`: 30 days
  99   - `90d`: 90 days
 100   - `365d`: 365 days
 101
 102 **[Response](https://formulae.brew.sh/api/analytics/install/homebrew-core/30d.json):**
 103
 104 {% include api-samples/analytics_install_homebrew_core_30d.md %}
 105
 106 ### List analytics events for all {{ site.taps.cask.name }} casks
 107
 108 List all the {{ site.taps.cask.fullname }} cask's analytics events for the `cask-install` category over a number of days, grouped by cask token.
 109 This is the data source for `brew info --analytics --cask <cask>`.
 110
 111 ```console
 112 curl https://formulae.brew.sh/api/analytics/cask-install/homebrew-cask/${DAYS}.json
 113 ```
 114
 115 **Variables:**
 116
 117 - `${DAYS}`: the number of days of analytics events, i.e.
 118   - `30d`: 30 days
 119   - `90d`: 90 days
 120   - `365d`: 365 days
 121
 122 **[Response](https://formulae.brew.sh/api/analytics/cask-install/homebrew-cask/30d.json):**
 123
 124 {% include api-samples/analytics_cask_install_homebrew_cask_30d.md %}