WIPE Around API

openapi: 3.2.0
info:
  title: 'WIPE : local businesses in Israel Around API'
  version: 1.0.0
  description: 'Search the local businesses of Israel (beauty and wellness, health, trades, food, shops, classes and more) by a plain Hebrew sentence, a town, a trade, a budget or a time. Read-only, no key, CORS open, about one request a second per caller. Results are ordered by how well they match the words and the trade, how near they are to a location when one is given (for businesses added from the towns around a town asked for, to that town''s centre), availability, how complete the page is, reviews and who runs the page. The words can lift a business above that order: one whose own name they give comes first, even outside the trade, the town, the budget or the time asked for; then one that says yes to what they ask of the place (a language spoken there, coming to the home) comes before one that has not; then one known to meet a budget or a time typed in them comes before one that has not said. Availability: any online booking counts a little, and free time in a WIPE booking calendar in the seven days from today counts more, most when its first free time is today or tomorrow and it has free time on five or more of those days. Reviews: only Around''s own, written through the link of a booking made on WIPE; reviews from other sites never count. Who runs the page: a page its owner verified counts most, then one its owner manages from a WIPE site, then a page from open data. So a business that books online, more so through a WIPE calendar with free time, and a page run from a WIPE site or verified, rank higher. Businesses that have not joined come from open data: © OpenStreetMap contributors (ODbL), Overture Maps Foundation (CDLA-Permissive-2.0), and the business-licensing registers of Tel Aviv-Yafo, Be''er Sheva (data.gov.il) and Kfar Saba (ODbL).'
  contact:
    name: WIPE
    url: https://iw.pe/
    email: support@iw.pe
servers:
- url: https://around.iw.pe
tags:
- name: Around
paths:
  /api/around/search:
    get:
      operationId: searchBusinesses
      summary: Find local businesses in Israel
      description: 'The town, the trade, a budget and a time are read from the Hebrew words in q. A budget (עד 400) or a time (היום or עכשיו for today; מחר, השבוע or בשבוע הקרוב for the week) read only from the words orders the results instead of filtering them. A business known to meet it is lifted (see the order): a published price for it at or under the budget, a free time then in a WIPE booking calendar. One that has not said (no published price for it, or no online booking) stays in the results, and its unconfirmed names what to ask it. One known not to meet it is left out, unless the words give its own name: a higher price, or online booking with no free time then in a WIPE booking calendar. Given as parameters, max and when filter instead.'
      parameters:
      - name: q
        in: query
        schema:
          type: string
          maxLength: 200
        description: 'What is wanted, in plain Hebrew, e.g. "קוסמטיקאית ברעננה" or "טיפול פנים בחיפה עד 400 השבוע". In English the town, a budget and a time are not read from the words (a business''s name and some trade words are): give them as city, max and when.'
      - name: city
        in: query
        schema:
          type: string
        description: A town's slug (tel-aviv, jerusalem, haifa, raanana…) or its Hebrew name.
      - name: kind
        in: query
        schema:
          type: string
        description: A trade's slug (cosmetics, hair, nails, body, electricians…).
      - name: lat
        in: query
        schema:
          type: number
        description: 'With lng, a point to measure from: how near a business is counts in the order, and a town in city or in the words no longer filters. The search reads the businesses within about 25 km of it, and any whose name carries the words wherever they are. The point is used only when both lat and lng are given and it lies in or near Israel.'
      - name: lng
        in: query
        schema:
          type: number
        description: With lat.
      - name: max
        in: query
        schema:
          type: integer
        description: Highest price in shekels.
      - name: when
        in: query
        schema:
          type: string
          enum:
          - today
          - week
        description: 'Only businesses with a free time in a WIPE booking calendar: later today (today) or in the seven days from today (week), Israel time. Free times are read only from the booking calendars of businesses that take bookings through their WIPE site, so a business without one never matches, even one that takes bookings by phone, on WhatsApp or through another booking site. The one exception is a business whose own name the words in q give: it comes first whatever its free times. When the search finds no business at all, the filter is let go: the results are the same search without it, and query.relaxed includes "when".'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 10
      responses:
        '200':
          description: Businesses, best first, each with how to reach it and why it fits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: object
                    properties:
                      relaxed:
                        type: array
                        items:
                          type: string
                        description: 'What the search let go because it found no business at all with it: "when" first, then "max_price"; and "kind→{trade}" when a treatment few businesses name was widened to its trade.'
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        url:
                          type: string
                          description: The business's page on WIPE Around (also as Markdown at <url>.md).
                        city:
                          type:
                          - string
                          - 'null'
                        address:
                          type:
                          - string
                          - 'null'
                        phone:
                          type:
                          - string
                          - 'null'
                        whatsapp:
                          type:
                          - string
                          - 'null'
                        booking:
                          type:
                          - string
                          - 'null'
                          description: A link that opens online booking on its page, when the business takes bookings through a WIPE site.
                        website:
                          type:
                          - string
                          - 'null'
                        priceFrom:
                          type:
                          - integer
                          - 'null'
                        nextFree:
                          type:
                          - object
                          - 'null'
                          properties:
                            day:
                              type: string
                            time:
                              type: string
                          description: The first free time in its WIPE booking calendar in the seven days from today; null for a business with no free time there and for every business without a WIPE booking calendar.
                        rating:
                          type:
                          - object
                          - 'null'
                        openNow:
                          type:
                          - boolean
                          - 'null'
                        why:
                          type: array
                          items:
                            type: string
                        unconfirmed:
                          type: array
                          items:
                            type: string
                          description: 'The budget or the time typed in the words that this business has not said whether it meets ("max_price": no published price for it; "when": no online booking): ask it.'
                  more:
                    type:
                    - string
                    - 'null'
        '429':
          description: Too many requests from one caller.
      tags:
      - Around