swagger: "2.0"
schemes:
  - https
host: www.sheerseo.com
basePath: /seo/api
info:
  contact:
    name: API Support
    url: https://www.sheerseo.com/seo-monitoring-tools/support.html
    x-twitter: sheerseo
  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."
  title: SheerSEO API
  version: 0.0.1
  x-apisguru-categories:
    - hosting
  x-logo:
    url: https://twitter.com/sheerseo/profile_image?size=original
  x-origin:
    - format: swagger
      url: https://www.sheerseo.com/api/swagger.yaml
      version: "2.0"
  x-providerName: sheerseo.com
consumes:
  - application/json; charset=utf-8
produces:
  - application/json; charset=utf-8
securityDefinitions:
  ApiKeyAuth:
    in: query
    name: apiKey
    type: apiKey
paths:
  /rank-collect:
    post:
      description: Submit serp jobs
      operationId: rankCollect
      parameters:
        - description: The body of the reqest to collect SERPs
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/CollectRequest"
      responses:
        "200":
          description: Success
          schema:
            $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"
      security:
        - ApiKeyAuth: []
  /rank-submit:
    post:
      description: Submit rank jobs
      operationId: rankSubmit
      parameters:
        - description: The body of the reqest to submit SERPs
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/rankSubmitRequest"
      responses:
        "200":
          description: Success
          schema:
            $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"
      security:
        - ApiKeyAuth: []
    x-swagger-router-controller: hello_world
  /serp-collect:
    post:
      description: Submit serp jobs
      operationId: serpCollect
      parameters:
        - description: The body of the reqest to collect SERPs
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/CollectRequest"
      responses:
        "200":
          description: Success
          schema:
            $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"
      security:
        - ApiKeyAuth: []
  /serp-submit:
    post:
      description: Submit serp jobs
      operationId: serpSubmit
      parameters:
        - description: The body of the reqest to submit SERPs
          in: body
          name: body
          required: true
          schema:
            $ref: "#/definitions/serpSubmitRequest"
      responses:
        "200":
          description: Success
          schema:
            $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"
      security:
        - ApiKeyAuth: []
    x-swagger-router-controller: hello_world
  /swagger:
    x-swagger-pipe: swagger_raw
definitions:
  CollectRequest:
    properties:
      task_ids:
        description: Receiving the request results through thier task id's
        items:
          example: 16b088653a6x782501
          type: string
        maxItems: 10
        minItems: 1
        type: array
    required:
      - task_ids
  ErrorResponse:
    properties:
      error_message:
        description: explanation of what was wrong
        type: string
    required:
      - error_message
  KeywordJobRank:
    properties:
      domain:
        description: The domain you want to check its rank for the keyword entered
        example: www.sheerseo.com
        type: string
      keyword:
        description: keyword (search term)
        example: seo software
        type: string
      localization_code:
        description: A code for the localization, which is a combination of country and language
        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
        example: us
        type: string
      localization_zip:
        description: option to localize the results per zip code
        example: "90210"
        type: string
      search_engine:
        default: google
        description: google/bing/google_mobile
        enum:
          - google
          - bing
          - google_mobile
        example: google
        type: string
    required:
      - keyword
      - localization_code
    type: object
  KeywordJobSerp:
    properties:
      keyword:
        description: keyword (search term)
        example: seo software
        type: string
      localization_code:
        description: A code for the localization, which is a combination of country and language
        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
        example: us
        type: string
      localization_zip:
        description: option to localize the results per zip code
        example: 90210
        type: string
      search_engine:
        default: google
        description: google/bing/google_mobile
        enum:
          - google
          - bing
          - google_mobile
        example: google
        type: string
    required:
      - keyword
      - localization_code
    type: object
  KeywordTask:
    properties:
      keyword:
        description: keyword (search term)
        example: seo software
        type: string
      localization_code:
        description: A code for the localization, which is a combination of country and language
        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
        example: us
        type: string
      localization_zip:
        description: option to localize the results per zip code
        example: 90210
        type: string
      search_engine:
        description: google/bing/google_mobile
        enum:
          - google
          - bing
          - google_mobile
        example: google
        type: string
      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
        enum:
          - ok
          - invalid
        example: ok
        type: string
      task_id:
        description: the assigned task id for this task. Should be used later in the serp-collect request
        example: 16ad9957b23x140753
        type: string
    required:
      - keyword
      - localization_code
    type: object
  rankCollectResponse:
    properties:
      tasks:
        items:
          properties:
            task_id:
              description: the id of the task you want to look for
              properties:
                error_message:
                  description: error message in case task status is invalid
                  example: ""
                  type: string
                keyword:
                  description: keyword (search term)
                  example: seo software
                  type: string
                local_pack_rank:
                  description: "relevent only to google: show the local pack rank of the domain in case exist"
                  example: 1
                  type: integer
                localization_code:
                  description: A code for the localization, which is a combination of country and language
                  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
                  example: us
                  type: string
                localization_zip:
                  description: option to localize the results per zip code
                  example: ""
                  type: string
                rank:
                  description: the exact rank of the domain in the search engine asked
                  example: 1
                  type: integer
                ready:
                  description: task ready indicator
                  enum:
                    - "true"
                    - "false"
                  example: "true"
                  type: string
                search_engine:
                  description: google/bing/google_mobile
                  enum:
                    - google
                    - bing
                    - google_mobile
                  example: google
                  type: string
                status:
                  description: task status in terms of success
                  enum:
                    - ok
                    - invalid
                  example: ok
                  type: string
              type: object
          type: object
        type: array
    title: Response for rank-collect request
  rankSubmitRequest:
    properties:
      priority:
        description: The priority for the keyword jobs submitted. High priority costs double credits. Default value is low.
        enum:
          - low
          - high
        example: high
        type: string
      tasks:
        description: The keyword RANK jobs. Maximum 1000 jobs per a single request.
        items:
          $ref: "#/definitions/KeywordJobRank"
        type: array
    required:
      - tasks
  rankSubmitResponse:
    description: Describes the result of uploading an image resource
    properties:
      error_message:
        type: string
      response_code:
        description: The request response_code.
        example: 200
        type: integer
      tasks:
        items:
          $ref: "#/definitions/KeywordTask"
        type: array
    required:
      - response_code
    title: Response for rank-submit request
    type: object
  serpCollectResponse:
    description: Describes the result of uploading an image resource
    properties:
      tasks:
        items:
          properties:
            task_id:
              properties:
                error_message:
                  description: error message in case task status is invalid
                  example: ""
                  type: string
                keyword:
                  description: keyword (search term)
                  example: seo software
                  type: string
                localization_code:
                  description: A code for the localization, which is a combination of country and language
                  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
                  example: us
                  type: string
                localization_zip:
                  description: option to localize the results per zip code
                  example: ""
                  type: string
                num_results:
                  description: number of results found in SERP
                  example: 100
                  type: integer
                organic_results:
                  items:
                    properties:
                      rank:
                        description: the url ranking number
                        example: 1
                        type: string
                      url:
                        example: www.sheerseo.com
                        type: string
                    type: object
                  type: array
                ready:
                  description: task ready indicator
                  enum:
                    - "true"
                    - "false"
                  example: "true"
                  type: string
                search_engine:
                  example: google
                  type: string
                status:
                  description: task status in terms of success
                  enum:
                    - ok
                    - invalid
                  example: ok
                  type: string
              type: object
          type: object
        type: array
    title: Response for serp-collect request
  serpSubmitRequest:
    properties:
      priority:
        description: The priority for the keyword jobs submitted. High priority costs double credits. Default value is low.
        enum:
          - low
          - high
        example: high
        type: string
      tasks:
        description: The keyword SERP jobs. Maximum 1000 jobs per a single request.
        items:
          $ref: "#/definitions/KeywordJobSerp"
        type: array
    required:
      - tasks
  serpSubmitResponse:
    description: Describes the result of uploading an image resource
    properties:
      error_message:
        type: string
      response_code:
        description: The request response_code.
        example: 200
        type: integer
      tasks:
        items:
          $ref: "#/definitions/KeywordTask"
        type: array
    required:
      - response_code
    title: Response for serp-submit request
    type: object
