(PureBasic) UPS Address Validation (City, State, Zip)

Demonstrates making a call to the UPS address validation REST API.

Chilkat PureBasic Module Download Chilkat PureBasic Module

IncludeFile "CkHttpResponse.pb"
IncludeFile "CkHttp.pb"
IncludeFile "CkStringBuilder.pb"
IncludeFile "CkJsonObject.pb"

Procedure ChilkatExample()

    ; This example requires the Chilkat API to have been previously unlocked.
    ; See Global Unlock Sample for sample code.

    success.i

    http.i = CkHttp::ckCreate()
    If http.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    url.s = "https://wwwcie.ups.com/rest/AV"

    ; Send an HTTP request with the following JSON body:

    ; {
    ;   "AccessRequest": {
    ;     "AccessLicenseNumber": "Your Access License Number",
    ;     "UserId": "Your Username",
    ;     "Password": "Your Password"
    ;   },
    ;   "AddressValidationRequest": {
    ;     "Request": {
    ;       "TransactionReference": {
    ;         "CustomerContext": "Your Customer Context"
    ;       },
    ;       "RequestAction": "AV"
    ;     },
    ;     "Address": {
    ;       "City": "ALPHARETTA",
    ;       "StateProvinceCode": "GA",
    ;       "PostalCode": "30005"
    ;     }
    ;   }
    ; }

    ; Build the above JSON.
    json.i = CkJsonObject::ckCreate()
    If json.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    CkJsonObject::ckUpdateString(json,"AccessRequest.AccessLicenseNumber","UPS_ACCESS_KEY")
    CkJsonObject::ckUpdateString(json,"AccessRequest.UserId","UPS_USERNAME")
    CkJsonObject::ckUpdateString(json,"AccessRequest.Password","UPS_PASSWORD")
    CkJsonObject::ckUpdateString(json,"AddressValidationRequest.Request.TransactionReference.CustomerContext","Your Customer Context")
    CkJsonObject::ckUpdateString(json,"AddressValidationRequest.Request.RequestAction","AV")
    CkJsonObject::ckUpdateString(json,"AddressValidationRequest.Address.City","ALPHARETTA")
    ; We're making an intentional mistake here by passing CA instead of GA.
    CkJsonObject::ckUpdateString(json,"AddressValidationRequest.Address.StateProvinceCode","CA")
    CkJsonObject::ckUpdateString(json,"AddressValidationRequest.Address.PostalCode","30005")

    sb.i = CkStringBuilder::ckCreate()
    If sb.i = 0
        Debug "Failed to create object."
        ProcedureReturn
    EndIf

    resp.i = CkHttp::ckPostJson3(http,url,"application/json",json)
    If CkHttp::ckLastMethodSuccess(http) <> 1
        Debug CkHttp::ckLastErrorText(http)
        CkHttp::ckDispose(http)
        CkJsonObject::ckDispose(json)
        CkStringBuilder::ckDispose(sb)
        ProcedureReturn
    EndIf

    Debug "status = " + Str(CkHttpResponse::ckStatusCode(resp))

    ; A 200 response status indicate success.
    If CkHttpResponse::ckStatusCode(resp) <> 200
        Debug CkHttpResponse::ckBodyStr(resp)
        Debug "Failed."
        CkHttpResponse::ckDispose(resp)

        CkHttp::ckDispose(http)
        CkJsonObject::ckDispose(json)
        CkStringBuilder::ckDispose(sb)
        ProcedureReturn
    EndIf

    CkJsonObject::ckLoad(json,CkHttpResponse::ckBodyStr(resp))
    CkJsonObject::setCkEmitCompact(json, 0)
    Debug CkJsonObject::ckEmit(json)

    ; A successful exact response looks like this:

    ; {
    ;   "AddressValidationResponse": {
    ;     "Response": {
    ;       "TransactionReference": {
    ;         "CustomerContext": "Your Customer Context"
    ;       },
    ;       "ResponseStatusCode": "1",
    ;       "ResponseStatusDescription": "Success"
    ;     },
    ;     "AddressValidationResult": {
    ;       "Rank": "1",
    ;       "Quality": "1.0",
    ;       "Address": {
    ;         "City": "ALPHARETTA",
    ;         "StateProvinceCode": "GA"
    ;       },
    ;       "PostalCodeLowEnd": "30005",
    ;       "PostalCodeHighEnd": "30005"
    ;     }
    ;   }
    ; }
    ; 

    ; A successful response that was not an exact match provides an array of closest matches, like this:

    ; {
    ;   "AddressValidationResponse": {
    ;     "Response": {
    ;       "TransactionReference": {
    ;         "CustomerContext": "Your Customer Context"
    ;         "Quality": "0.9875",
    ;         "Address": {
    ;       },
    ;       "ResponseStatusCode": "1",
    ;       "ResponseStatusDescription": "Success"
    ;     },
    ;     "AddressValidationResult": [
    ;       {
    ;         "Rank": "1",
    ;           "City": "ALPHARETTA",
    ;           "StateProvinceCode": "GA"
    ;         },
    ;         "PostalCodeLowEnd": "30005",
    ;         "PostalCodeHighEnd": "30005"
    ;       },
    ;       {
    ;         "Rank": "2",
    ;         "Quality": "0.9750",
    ;         "Address": {
    ;           "City": "ALPHARETTA",
    ;           "StateProvinceCode": "GA"
    ;         },
    ;         "PostalCodeLowEnd": "30004",
    ;         "PostalCodeHighEnd": "30004"
    ;       },
    ;       {
    ;         "Rank": "3",
    ;         "Quality": "0.9750",
    ;         "Address": {
    ;           "City": "ALPHARETTA",
    ;           "StateProvinceCode": "GA"
    ;         },
    ;         "PostalCodeLowEnd": "30009",
    ;         "PostalCodeHighEnd": "30009"
    ;       }
    ;     ]
    ;   }
    ; }

    ; Use the online tool at Generate JSON Parsing Code
    ; to generate JSON parsing code.

    customerContext.s
    statusCode.s
    statusDescription.s
    resultRank.s
    resultQuality.s
    city.s
    provinceCode.s
    postalCodeLowEnd.s
    postalCodeHighEnd.s
    rank.s
    quality.s
    addressCity.s
    addressStateProvinceCode.s

    numResults.i = CkJsonObject::ckSizeOfArray(json,"AddressValidationResponse.AddressValidationResult")
    If numResults < 0

        ; Here's parse code for the above JSON exact response:
        customerContext = CkJsonObject::ckStringOf(json,"AddressValidationResponse.Response.TransactionReference.CustomerContext")
        statusCode = CkJsonObject::ckStringOf(json,"AddressValidationResponse.Response.ResponseStatusCode")
        statusDescription = CkJsonObject::ckStringOf(json,"AddressValidationResponse.Response.ResponseStatusDescription")
        resultRank = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult.Rank")
        resultQuality = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult.Quality")
        city = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult.Address.City")
        provinceCode = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult.Address.StateProvinceCode")
        postalCodeLowEnd = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult.PostalCodeLowEnd")
        postalCodeHighEnd = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult.PostalCodeHighEnd")

        Debug "Exact match!"
        Debug "postal code: " + postalCodeLowEnd

    Else

        Debug "Non-Exact match."

        customerContext = CkJsonObject::ckStringOf(json,"AddressValidationResponse.Response.TransactionReference.CustomerContext")
        statusCode = CkJsonObject::ckStringOf(json,"AddressValidationResponse.Response.ResponseStatusCode")
        statusDescription = CkJsonObject::ckStringOf(json,"AddressValidationResponse.Response.ResponseStatusDescription")
        i.i = 0
        While i < numResults
            CkJsonObject::setCkI(json, i)
            rank = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult[i].Rank")
            Debug "rank: " + rank
            quality = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult[i].Quality")
            addressCity = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult[i].Address.City")
            Debug "addressCity: " + addressCity
            addressStateProvinceCode = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult[i].Address.StateProvinceCode")
            postalCodeLowEnd = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult[i].PostalCodeLowEnd")
            Debug "postal code: " + postalCodeLowEnd
            postalCodeHighEnd = CkJsonObject::ckStringOf(json,"AddressValidationResponse.AddressValidationResult[i].PostalCodeHighEnd")
            i = i + 1
        Wend
    EndIf

    CkHttpResponse::ckDispose(resp)



    CkHttp::ckDispose(http)
    CkJsonObject::ckDispose(json)
    CkStringBuilder::ckDispose(sb)


    ProcedureReturn
EndProcedure