openapi: 3.0.3
info:
  title: Prayer Times API
  version: "1"
  description: Prayer times and location lookup, backed by Diyanet data.
externalDocs:
  description: Source code
  url: https://git.abdus.dev/abdus/prayertimes-go/
servers:
  - url: /
paths:
  /api/v1/diyanet/location:
    get:
      summary: Search locations
      description: Search locations by free-text query, or find the nearest location to a coordinate pair.
      parameters:
        - name: query
          in: query
          description: Free-text location search. Mutually exclusive with latitude/longitude.
          schema:
            type: string
        - name: latitude
          in: query
          description: Required together with longitude when query is omitted.
          schema:
            type: number
            format: double
        - name: longitude
          in: query
          description: Required together with latitude when query is omitted.
          schema:
            type: number
            format: double
      responses:
        "200":
          description: Matching locations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  locations:
                    type: array
                    items:
                      $ref: "#/components/schemas/Location"
        "400":
          description: Missing both query and coordinates.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/diyanet/prayertimes:
    get:
      summary: Get prayer times
      description: Get prayer times by location ID, or by coordinates.
      parameters:
        - name: location_id
          in: query
          description: Mutually exclusive with latitude/longitude.
          schema:
            type: string
        - name: latitude
          in: query
          schema:
            type: number
            format: double
        - name: longitude
          in: query
          schema:
            type: number
            format: double
        - name: utc
          in: query
          description: Return timestamps in UTC instead of the location's local timezone.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Prayer times for the resolved location.
          content:
            application/json:
              schema:
                type: object
                properties:
                  location:
                    $ref: "#/components/schemas/Location"
                  prayertimes:
                    type: array
                    items:
                      $ref: "#/components/schemas/PrayerTimes"
        "400":
          description: Missing both location_id and coordinates.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: Invalid location.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Location:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        ascii_name:
          type: string
        alternate_names:
          type: string
        country_code:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        timezone:
          type: string
    PrayerTimes:
      type: object
      properties:
        date:
          type: string
          format: date
        date_hijri:
          type: string
        fajr:
          type: string
          example: "05:47"
        sunrise:
          type: string
        dhuhr:
          type: string
        asr:
          type: string
        sunset:
          type: string
        maghrib:
          type: string
        isha:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string