swagger: "2.0"
info:
  description: 'Sheerseo API has 2 stages:<br>First stage - initiating the task: You fill in your task and receive in return the task id. <br>Second stage - collecting the results: send a request containing the task ids you got at the first stage and collecting the results.'
  version: "0.0.1"
  title: SheerSEO API
  contact:
    name: API Support
    url: https://www.sheerseo.com/seo-monitoring-tools/support.html
# during dev, should point to your local machine
host: www.sheerseo.com
securityDefinitions:
  ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey
# basePath prefixes all resource paths 
basePath: /seo/api
# 
schemes:
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - "application/json; charset=utf-8"
# format of the responses to the client (Accepts)
produces:
  - "application/json; charset=utf-8"
paths:
  /serp-submit:
    # binds a127 app logic to a route
    x-swagger-router-controller: hello_world
    post:
      description: Submit serp jobs 
      # used as the method name of the controller
      operationId: serpSubmit
      security:
        - ApiKeyAuth: []
      parameters:
        - name: body
          in: body
          description: The body of the reqest to submit SERPs
          required: true
          schema:
            $ref: '#/definitions/serpSubmitRequest'
      responses:
        200:
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/serpSubmitResponse"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/ErrorResponse"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/ErrorResponse"
        503:
          description: Server Overload
          schema:
            $ref: "#/definitions/ErrorResponse"
  /serp-collect:
    post:
      description: Submit serp jobs 
      # used as the method name of the controller
      security:
        - ApiKeyAuth: []
      operationId: serpCollect
      parameters:
        - name: body
          in: body
          description: The body of the reqest to collect SERPs
          required: true
          schema:
            $ref: '#/definitions/CollectRequest'
      responses:
        200:
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/serpCollectResponse"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/ErrorResponse"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/ErrorResponse"
        503:
          description: Server Overload
          schema:
            $ref: "#/definitions/ErrorResponse"
  /rank-submit:
    # binds a127 app logic to a route
    x-swagger-router-controller: hello_world
    post:
      description: Submit rank jobs 
      # used as the method name of the controller
      security:
        - ApiKeyAuth: []
      operationId: rankSubmit
      parameters:
        - name: body
          in: body
          description: The body of the reqest to submit SERPs
          required: true
          schema:
            $ref: '#/definitions/rankSubmitRequest'
      responses:
        200:
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/rankSubmitResponse"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/ErrorResponse"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/ErrorResponse"
        503:
          description: Server Overload
          schema:
            $ref: "#/definitions/ErrorResponse"
  /rank-collect:
    post:
      description: Submit serp jobs 
      # used as the method name of the controller
      security:
        - ApiKeyAuth: []
      operationId: rankCollect
      parameters:
        - name: body
          in: body
          description: The body of the reqest to collect SERPs
          required: true
          schema:
            $ref: '#/definitions/CollectRequest'
      responses:
        200:
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/rankCollectResponse"
        400:
          description: Bad Request
          schema:
            $ref: "#/definitions/ErrorResponse"
        404:
          description: Not Found
          schema:
            $ref: "#/definitions/ErrorResponse"
        503:
          description: Server Overload
          schema:
            $ref: "#/definitions/ErrorResponse"
  /swagger:
    x-swagger-pipe: swagger_raw
# complex objects have schema definitions
definitions:

  ErrorResponse:
    required:
      - error_message
    properties:
      error_message:
        type: string
        description: explanation of what was wrong
  KeywordJobSerp:
    type: object
    required:
      - keyword
      - localization_code
    properties:
      keyword: 
        type: string
        description: keyword (search term)
        example: seo software
      search_engine: 
        type: string
        description: google/bing/google_mobile
        default: google
        example: google
        enum:
          - google
          - bing
          - google_mobile
      localization_code: 
        type: string
        description: A code for the localization, which is a combination of country and language
        example: us
        enum:
          - us
          - uk
          - au
          - br
          - be_dutch
          - be_french
          - ca
          - de
          - es
          - ie
          - il
          - nl
          - sg
          - za
          - it
          - is
          - ch
          - fr
          - se
          - at
          - dk
          - nz
          - gr
          - no
          - in
          - ms
          - pl
          - hk
          - id
          - ru
          - ae
          - fi
          - pt
          - mx
          - tr
          - cl
          - jp
          - ar
      localization_zip: 
        description: option to localize the results per zip code
        type: string
        example: 90210
  KeywordJobRank:
    type: object
    required:
      - keyword
      - localization_code
    properties:
      keyword: 
        type: string
        description: keyword (search term)
        example: seo software
      search_engine: 
        type: string
        description: google/bing/google_mobile
        default: google
        example: google
        enum:
          - google
          - bing
          - google_mobile
      localization_code: 
        type: string
        description: A code for the localization, which is a combination of country and language
        example: us
        enum:
          - us
          - uk
          - au
          - br
          - be_dutch
          - be_french
          - ca
          - de
          - es
          - ie
          - il
          - nl
          - sg
          - za
          - it
          - is
          - ch
          - fr
          - se
          - at
          - dk
          - nz
          - gr
          - no
          - in
          - ms
          - pl
          - hk
          - id
          - ru
          - ae
          - fi
          - pt
          - mx
          - tr
          - cl
          - jp
          - ar
      localization_zip: 
        description: option to localize the results per zip code
        type: string
        example: "90210"
      domain:
        description: The domain you want to check its rank for the keyword entered
        type: string
        example: "www.sheerseo.com"
  serpSubmitRequest:
    required:
      - tasks
    properties:
      priority:
        type: string
        description: The priority for the keyword jobs submitted. High priority costs double credits. Default value is low.
        example: high
        enum:
          - low
          - high
      tasks:
        description: The keyword SERP jobs. Maximum 1000 jobs per a single request. 
        type: "array"
        items:
          $ref: '#/definitions/KeywordJobSerp'
  serpSubmitResponse:
    title: Response for serp-submit request
    description: Describes the result of uploading an image resource
    type: object
    required:
      - response_code
    properties:
      response_code:
        description: The request response_code.
        type: integer
        example: 200
      error_message:
        type: string
      tasks:
        type: "array"
        items:
          $ref: '#/definitions/KeywordTask'
  CollectRequest:
    required:
      - task_ids
    properties:
      task_ids:
        description: Receiving the request results through thier task id's
        type: "array"
        items:
          type: "string"
          example: '16b088653a6x782501'
        minItems: 1
        maxItems: 10
  KeywordTask:
    type: object
    required:
      - keyword
      - localization_code
    properties:
      keyword: 
        type: string
        description: keyword (search term)
        example: seo software
      search_engine: 
        type: string
        description: google/bing/google_mobile
        example: google
        enum:
          - google
          - bing
          - google_mobile
      localization_code: 
        type: string
        description: A code for the localization, which is a combination of country and language
        example: us
        enum:
          - us
          - uk
          - au
          - br
          - be_dutch
          - be_french
          - ca
          - de
          - es
          - ie
          - il
          - nl
          - sg
          - za
          - it
          - is
          - ch
          - fr
          - se
          - at
          - dk
          - nz
          - gr
          - no
          - in
          - ms
          - pl
          - hk
          - id
          - ru
          - ae
          - fi
          - pt
          - mx
          - tr
          - cl
          - jp
          - ar
      localization_zip: 
        description: option to localize the results per zip code
        type: string
        example: 90210
      task_id: 
        description: the assigned task id for this task. Should be used later in the serp-collect request
        type: string
        example: 16ad9957b23x140753
      status: 
        description: status of this task request. "ok" means we're working on collecting it. "invalid" means there was an error and it won't be collected
        type: string
        example: ok
        enum:
          - ok
          - invalid
  rankSubmitRequest:
    required:
      - tasks
    properties:
      priority:
        type: string
        description: The priority for the keyword jobs submitted. High priority costs double credits. Default value is low.
        example: high
        enum:
          - low
          - high
      tasks:
        description: The keyword RANK jobs. Maximum 1000 jobs per a single request. 
        type: "array"
        items:
          $ref: '#/definitions/KeywordJobRank'
  rankSubmitResponse:
    title: Response for rank-submit request
    description: Describes the result of uploading an image resource
    type: object
    required:
      - response_code
    properties:
      response_code:
        description: The request response_code.
        type: integer
        example: 200

      error_message:
        type: string
      tasks:
        type: "array"
        items:
          $ref: '#/definitions/KeywordTask'
  serpCollectResponse:
    title: Response for serp-collect request
    description: Describes the result of uploading an image resource
    properties:
      tasks:
        type: "array"
        items:
            type: object
            properties:
              task_id: 
                type: object
                properties:
                  ready:
                    type: string
                    example: "true"
                    description: task ready indicator
                    enum:
                      - "true"
                      - "false"
                  keyword:
                    type: string
                    description: keyword (search term)
                    example: "seo software"
                  search_engine:
                    type: string
                    example: "google"
                  localization_code:
                    type: string
                    description: A code for the localization, which is a combination of country and language
                    example: "us"
                    enum:
                      - us
                      - uk
                      - au
                      - br
                      - be_dutch
                      - be_french
                      - ca
                      - de
                      - es
                      - ie
                      - il
                      - nl
                      - sg
                      - za
                      - it
                      - is
                      - ch
                      - fr
                      - se
                      - at
                      - dk
                      - nz
                      - gr
                      - no
                      - in
                      - ms
                      - pl
                      - hk
                      - id
                      - ru
                      - ae
                      - fi
                      - pt
                      - mx
                      - tr
                      - cl
                      - jp
                      - ar
                  localization_zip:
                    type: string
                    example: ""
                    description: option to localize the results per zip code
                  status:
                    type: string
                    example: "ok"
                    description: task status in terms of success
                    enum:
                     - "ok"
                     - "invalid"
                  error_message:
                    type: string
                    example: ""
                    description: "error message in case task status is invalid"
                  num_results:
                    type: integer
                    example: 100
                    description: "number of results found in SERP"
                  organic_results:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          example: "www.sheerseo.com"
                        rank:
                          type: string
                          example: 1
                          description: "the url ranking number"
  rankCollectResponse:
    title: Response for rank-collect request
    properties:
      tasks:
        type: "array"
        items:
                type: object
                properties:
                  task_id: 
                    description: the id of the task you want to look for
                    type: object
                    properties:
                      ready:
                        type: string
                        example: "true"
                        description: task ready indicator
                        enum:
                          - "true"
                          - "false"
                      keyword:
                        type: string
                        example: "seo software"
                        description: keyword (search term)
                      search_engine:
                        type: string
                        example: "google"
                        description: google/bing/google_mobile
                        enum:
                          - google
                          - bing
                          - google_mobile
                      localization_code:
                        type: string
                        description: A code for the localization, which is a combination of country and language
                        example: us
                        enum:
                          - us
                          - uk
                          - au
                          - br
                          - be_dutch
                          - be_french
                          - ca
                          - de
                          - es
                          - ie
                          - il
                          - nl
                          - sg
                          - za
                          - it
                          - is
                          - ch
                          - fr
                          - se
                          - at
                          - dk
                          - nz
                          - gr
                          - no
                          - in
                          - ms
                          - pl
                          - hk
                          - id
                          - ru
                          - ae
                          - fi
                          - pt
                          - mx
                          - tr
                          - cl
                          - jp
                          - ar
                      localization_zip:
                        type: string
                        example: ""
                        description: option to localize the results per zip code
                      status:
                        type: string
                        example: "ok"
                        description: task status in terms of success
                        enum:
                          - "ok"
                          - "invalid"
                      error_message:
                        type: string
                        example: ""
                        description: "error message in case task status is invalid"
                      rank:
                        type: integer
                        example: 1
                        description: "the exact rank of the domain in the search engine asked"
                      local_pack_rank:
                        type: integer
                        example: 1
                        description: "relevent only to google: show the local pack rank of the domain in case exist"
      
    