openapi: 3.0.0
info:
  version: "0.0"
  title: Qomon
  description: |-
    This is Qomon's API definition.

    To get an authorization go to [Qomon's setting page](https://qomon.app/settings/extensions/connect) and create an API key.
servers:
  - description: Qomon production
    url: https://qomon.app/api
  - description: Qomon integration
    url: https://test.quorumapps.com/api
tags:
  - name: Search addresses
    description: Search addresses by query


paths:
  /geocode/forward:
    get:
      tags:
        - Search addresses
      summary: Geocode an address
      description: |-
        Get the location of an address. <br>
        
        The address provided must be inside the country of user space.
      parameters:
        - name: housenumber
          in: query
          description: House number
          required: false
          schema:
            type: string
        - name: street
          in: query
          description: Street
          required: true
          schema:
            type: string
        - name: city
          in: query
          description: City
          required: true
          schema:
            type: string
        - name: county
          in: query
          description: County
          required: false
          schema:
            type: string
        - name: postalcode
          in: query
          description: Postal code
          required: false
          schema:
            type: string
        - name: state
          in: query
          description: State
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [success]
                  data:
                    type: object
                    properties:
                      address:
                        type: object
                        $ref: '#/components/schemas/Address'
        '404':
          description: Not found

  /geocode/reverse:
    get:
      tags:
        - Search addresses
      summary: Reverse geocode
      description: |-
        Get the address at a given location. <br>
        `city` and `street` are optional parameters used to filter the results. It does
        not improve the accuracy of the result. <br>

        The location provided must be inside the country of user space.
      parameters:
        - name: lat
          in: query
          description: Latitude
          required: true
          schema:
            type: number
        - name: lon
          in: query
          description: Longitude
          required: true
          schema:
            type: number
        - name: city
          in: query
          description: City
          required: false
          schema:
            type: string
        - name: street
          in: query
          description: Street
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [success]
                  data:
                    type: object
                    properties:
                      address:
                        $ref: '#/components/schemas/Address'
                      distance:
                        type: number
        '404':
          description: Not found
                  
  /geocode/search:
    get:
      tags:
        - Search addresses
      summary: Search addresses
      description: |-
        Search addresses by query.<br>
        If `type` indicate what kind of query is provided, if not provided, the default is address for a full address search. <br>
        When searching by postcode the query must be a whole postcode. Supported country for postcode search are:
          - Canada, United Kingdom, United States (partial dataset) -> return address down to street level
          - France -> return address down to city level

        Provide `lat` and `lon` allow to search around a location. Results are sorted by distance.
        Request ID is used to track the request and for chained requests it can improve the response time by using directly the correct geo provider.

        The search is limited to the country of user space.
      parameters:
        - name: query
          in: query
          description: Query
          required: true
          schema:
            type: string
        - name: lat
          in: query
          description: Latitude
          required: false
          schema:
            type: number
        - name: lon
          in: query
          description: Longitude
          required: false
          schema:
            type: number
        - name: type
          in: query
          description: Type
          required: false
          schema:
            type: string
            enum: [address, postcode, city]
            default: address
        - name: requestId
          in: query
          description: Request ID
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [success]
                  data:
                    type: object
                    properties:
                      addresses:
                        type: array
                        items:
                          $ref: '#/components/schemas/Address'
                      requestId:
                        type: string
        '404':
          description: Not found



components:
  schemas:
    Address:
      type: object
      properties:
        housenumber:
          type: string
          example: "1124"
        street:
          type: string
          example: "Greenwood Ave"
        city:
          type: string
          example: "Toronto"
        county:
          type: string
          example: "Toronto"
        postalcode:
          type: string
          example: "M4J 4E5"
        state:
          type: string
          example: "Ontario"
        country:
          type: string
          example: "Canada"
        score:
          type: number
          example: 0.786
        latitude:
          type: string
          example: "43.678"
        longitude:
          type: string
          example: "-79.347"