swagger: "2.0"
schemes:
  - https
host: sandbox.whapi.com
basePath: /v2/locations
info:
  contact:
    x-twitter: WilliamHill
  description: The Locations API is a collection of methods that support geographical information. The first method is an address lookup service for UK addresses. This service can be used to provide a new customer with a list of possible addresses from which they can populate a registration form.
  title: Locations
  version: "2.0"
  x-apisguru-categories:
    - entertainment
  x-logo:
    url: https://twitter.com/WillHillHelp/profile_image?size=original
  x-origin:
    - format: swagger
      url: https://developer.williamhill.com/wh-docs/docs-sdks/locations/swagger/docs
      version: "2.0"
  x-providerName: whapi.com
  x-serviceName: locations
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  apiKey:
    description: A unique identifier of your application that is generated by the API portal and presented in the header.
    in: header
    name: apiKey
    type: apiKey
security:
  - apiKey: []
parameters:
  apiKey:
    description: A unique identifier of your application that is generated by the API portal and presented in the header.
    in: header
    name: apiKey
    required: true
    type: string
    x-eg: l7xxa54460c573b5497c9b24b505xxxxxxxx
  countryCode:
    description: Code of the country
    in: path
    name: countryCode
    required: true
    type: string
    x-eg: GB
  currencyCode:
    description: Code of the currency
    in: path
    name: currencyCode
    required: true
    type: string
    x-eg: GBP
  houseNum:
    description: House number or name of the address.
    in: query
    name: houseNum
    required: true
    type: string
    x-eg: 4
  postCode:
    description: Postcode of the address, no spaces required.
    in: query
    name: postCode
    required: true
    type: string
    x-eg: GX11AA
paths:
  /address/lookup/:
    get:
      description: |
        Retrieves a list of addresses when supplied with a house number or name and a postcode. It is generally used during customer registration to provide a list of possible addresses from where the customer can select their own address details.
      operationId: addressLookup
      parameters:
        - description: House number or name of the address.
          in: query
          name: houseNum
          required: true
          type: string
          x-eg: 4
        - description: Postcode of the address, no spaces required.
          in: query
          name: postCode
          required: true
          type: string
          x-eg: GX11AA
      responses:
        "200":
          description: Success
          examples:
            application/json: |
              {
                "addresses": 
                [
                  {
                    "fullAddress": "4 Bywater Place, LONDON, SE16 5ND",
                    "street": "4 Bywater Place",
                    "postcode": "SE16 5ND",
                    "city": "London",
                    "county": "London"
                  }
                ]
              }        
          schema:
            $ref: "#/definitions/addresses"
        "400":
          description: Missing or Invalid Parameter
          examples:
            application/json: |
              {
                "errors":
                [
                  {
                    "code":"10070",
                    "message":"Missing Parameter",
                    "field":"postCode"
                  },
                  {
                    "code":"10071",
                    "message":"Invalid Parameter",
                    "field":"postCode"
                  }
                ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
        "404":
          description: Address not found
          examples:
            application/json: |
              {
                "errors" : 
                [
                  {
                    "code":"20301",
                    "message":"Could not find any addresses",
                    "field":"postCode"
                  }
                ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
      tags:
        - Locations
      x-canReturnErrors:
        - 20301
        - 20303
        - 10070
        - 10071
  /countries/:
    get:
      description: Retrieves a list of countries and its currencies.
      operationId: getCountries
      parameters: []
      responses:
        "200":
          description: Successful response
          examples:
            application/json: |
              {
                  "countries": 
                  [
                      {
                          "code": "GB",
                          "name": "United Kingdom", 
                          "currencyCode" : "GBP", 
                          "dialCode" : "+44"
                      }
                  ]
              }
          schema:
            $ref: "#/definitions/countries"
        "400":
          description: Missing or Invalid Parameter
          examples:
            application/json: |
              {
                  "errors" : 
                  [
                      {
                        "code":"10070",
                        "message":"Missing Parameter",
                        "field":"postCode"
                      },
                      {
                        "code":"10071",
                        "message":"Invalid Parameter",
                        "field":"postCode"
                      }    
                  ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
        "404":
          description: Country/Countries not found
          examples:
            application/json: |
              {
                  "errors" : 
                  [
                      {
                        "code":"20303",
                        "message":"Country not Found"
                      }
                  ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
      tags:
        - Locations
      x-canReturnErrors:
        - 20303
  "/countries/{countryCode}":
    get:
      description: Retrieves the specified country and its currency.
      operationId: getCountry
      parameters:
        - description: Code of the country
          in: path
          name: countryCode
          required: true
          type: string
          x-eg: GB
      responses:
        "200":
          description: Success
          examples:
            application/json: |
              {
                "code":"gb",
                "name":"Great Britain",
                "currencyCode":"GBP",
                "dialCode":"+44"
              }
          schema:
            $ref: "#/definitions/country"
        "400":
          description: Missing or Invalid Parameter
          examples:
            application/json: |
              {
                  "errors" : 
                  [
                      {
                        "code":"10070",
                        "message":"Missing Parameter",
                        "field":"postCode"
                      },
                      {
                        "code":"10071",
                        "message":"Invalid Parameter",
                        "field":"postCode"
                      }    
                  ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
        "404":
          description: Country/Countries not found
          examples:
            application/json: |
              {
                  "errors" : 
                  [
                      {
                        "code":"20303",
                        "message":"Country not Found"
                      }
                  ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
      tags:
        - Locations
      x-canReturnErrors:
        - 20303
        - 10070
        - 10071
  /currencies/:
    get:
      description: Retreives the list of currencies.
      operationId: getCurrencies
      parameters: []
      responses:
        "200":
          description: Success
          examples:
            application/json: |
              {
                "currencies": 
                [
                  {
                    "code":"GBP",
                    "name":"Pound",
                    "minDeposit":"5.00",
                    "maxDeposit":"100.00",
                    "minWithdrawal":"20.00",
                    "maxWithdrawal":"1000.00",
                    "exchangeRate":"1.00"
                  }
                ]
              }
          schema:
            $ref: "#/definitions/currencies"
        "404":
          description: Currency not found
          examples:
            application/json: |
              {
                  "errors" : 
                  [
                      {
                        "code":"20304",
                        "message":"Currency not Found"
                      }
                  ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
      tags:
        - Locations
      x-canReturnErrors:
        - 20304
  "/currencies/{currencyCode}":
    get:
      description: Retreives the specified currency.
      operationId: getCurrency
      parameters:
        - description: Code of the currency
          in: path
          name: currencyCode
          required: true
          type: string
          x-eg: GBP
      responses:
        "200":
          description: Success
          examples:
            application/json: |
              {
                  "code":"GBP",
                  "name":"Pound",
                  "minDeposit":"5.00",
                  "maxDeposit":"100.00",
                  "minWithdrawal":"20.00",
                  "maxWithdrawal":"1000.00",
                  "exchangeRate":"1.00"
              }
          schema:
            $ref: "#/definitions/currency"
        "400":
          description: Missing or Invalid Parameter
          examples:
            application/json: |
              {
                  "errors" : 
                  [
                      {
                        "code":"10070",
                        "message":"Missing Parameter",
                        "field":"postCode"
                      },
                      {
                        "code":"10071",
                        "message":"Invalid Parameter",
                        "field":"postCode"
                      }    
                  ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
        "404":
          description: Currency not found
          examples:
            application/json: |
              {
                  "errors" : 
                  [
                      {
                        "code":"20304",
                        "message":"Currency not Found"
                      }
                  ]
              }
          schema:
            $ref: "#/definitions/locationsErrors"
      tags:
        - Locations
      x-canReturnErrors:
        - 20304
        - 10070
        - 10071
definitions:
  address:
    properties:
      city:
        description: The name of the postal city/town
        type: string
      county:
        description: The name of the county
        type: string
      fullAddress:
        description: The customer’s complete address including postcode
        type: string
      postCode:
        description: The postcode of the address
        type: string
      street:
        description: The name of the street including the house number/house name
        type: string
    title: address
    type: object
  addresses:
    properties:
      addresses:
        items:
          $ref: "#/definitions/address"
        type: array
    type: object
  countries:
    properties:
      countries:
        items:
          $ref: "#/definitions/country"
        type: array
    type: object
  country:
    properties:
      code:
        description: The code of the country
        type: string
      currencyCode:
        description: The currency code
        type: string
      dialCode:
        description: The dial code of the country
        type: string
      name:
        description: The name of the country
        type: string
    title: country
    type: object
  currencies:
    properties:
      currencies:
        items:
          $ref: "#/definitions/currency"
        type: array
    type: object
  currency:
    properties:
      code:
        description: The code of the currency
        type: string
      exchangeRate:
        description: The exchange rate for the currency
        format: double
        type: number
      maxDeposit:
        description: The maximum deposit for the currency
        format: double
        type: number
      maxWithdrawal:
        description: The maximum withdrawl for the currency
        format: double
        type: number
      minDeposit:
        description: The minimum deposit for the currency
        format: double
        type: number
      minWithdrawal:
        description: The minimum withdrawal for the currency
        format: double
        type: number
      name:
        description: The name of the currency
        type: string
    title: currency
  error:
    properties:
      code:
        description: A unique William Hill identifier for the error
        type: string
      field:
        description: To help pinpoint the exact parameter where a request has failed
        type: string
      message:
        description: A unique William Hill text string to enable you to identify the error (in English only)
        type: string
    type: object
  locationsErrors:
    properties:
      errors:
        items:
          $ref: "#/definitions/error"
        type: array
    type: object
x-customerrors:
  - code: 20301
    message: Could not find any addresses
    status: 404
  - code: 20302
    message: Result limit has been exceeded
    status: 400
  - code: 20303
    message: Country not found
    status: 404
  - code: 20304
    message: Currency not found
    status: 404
x-docchapters:
  - fieldSelection
  - apiSummary
  - headAndOptions
  - docsAndSdks
  - errorHandling
  - statusCodes
