BricksAndMortar™

 

Overview

This document provides a technical overview of the AliLocator™ SaaS API and its endpoints; byAliLocator and byStreetAddress. A client utilizes these endpoints by submitting input and, assuming the input properly validates, the endpoint will return the associated information.

HTTPS only

Each SaaS API endpoint exposes an HTTPS URL which accepts a request and returns a response. The client accesses the endpoint by composing an HTTPS request with well-formed request parameters, GET (via URI) or POST (via standard properties or JSON – XML is planned). Upon submitting the request, a well formed JSON (XML is planned) response is returned.

Stateless only

As the endpoint is stateless, it does not retain any state whatsoever between calls to the endpoint. As such, all data required to generate a valid and useful response must be supplied within the corresponding request parameters.

Each endpoint versioned

Each endpoint is also versioned with specific extension in the “YYYYMMDD” format. So for a given endpoint name and version (ex: byAliLocator.20170320), the input parameters will not change in any way or meaning and the output will not change in any way or meaning for the existence of that particular endpoint.version.

In other words, all of the specific input parameters and output formatting for this particular endpoint.version are irreversibly and immutably locked down. Any additional functionality desired to be added to the endpoint will require releasing an entirely new version. This policy is enforced by the SaaS provider to separate the SaaS clients from any possible production breaking changes when an updated version of an endpoint is released. It also keeps the SaaS provider from having to synchronize production changing releases with any/all SaaS clients.

As such, this means the specific endpoint version must be specified by the client for each request. It also means if/when an expanded response is desired (for example, wanting to receive the new “geohashes” sub-section) by the client, explicitly updating the client to send a new/different version number for the same endpoint to the SaaS web-service is required. Transitioning to the new endpoint.version likely involves having to adjust to both new/changed/removed input parameters and new/changed/removed response sub-sections and fields.

SaaS API

Input

The client submits a request to an endpoint via HTTPS. The request must contain a list of accepted parameters. If using HTTP GET, the parameters must be URI encoded; i.e. spaces replaced with either “+” or escaped using “%20” and all other special characters escaped. If using HTTP POST, when using parameters, they must be properly encoded in the POST header or the supplied (JSON) document must be well formed.

If the URL is correct and a successful connection and call is made to the endpoint, the client’s request parameters will be echoed within the request section of the well-formed (JSON) response.

HTTPS Request

The client may call the endpoint with either of the HTTPS request types, GET or POST. The endpoint behaves exactly the same regardless of which is used; i.e. it does not distinguish between the two HTTPS request types.

Example request URLs will be provided below (at 2.1.2).

Root URL

The client must use the well-formed URL below to attach to the endpoint when making a web-service call:

https://bamsaas.com/api

This particular URL is associated with a load balancer and not with a specific endpoint server (of which there are several servers behind the load balancer). In order to avoid potential issues arising from DNS reconfiguration of either the load balancer and/or the endpoint servers, when implementing your client, please refrain from using any explicit IP address.

Input Parameters

There are input parameters which exist regardless of specific endpoint, some of which are required.

General

Name Required Notes
transaction.endPoint.name Yes Valid values are “byAliLocator” and “byStreetAddress”
transaction.endPoint.version Yes Valid values are “20170320” and “20161102” (“20161102” has been deprecated and will be removed in a future release)
transaction.endPoint.kind Yes Valid values are “Option” and “Payload”
transaction.endPoint.format.output Yes Valid values are “HTML” and “JSON” (and eventually “XML”)
transaction.endPoint.repeatCount No Valid values are 1 to 100, defaulting to 10
clientCredentials.accessKey No* Required if not provided via OAuth 1.0
clientCredentials.secretKey No* Required if not provided via OAuth 1.0
request.trackingLabel No Client value for tracking entire batch identity

There are also input parameters specific to each particular endpoint. All endpoints designed to accept batches use a simple prefix pattern to group sets of input parameters per batch row. The prefix will look something like “request.location.0…”. The digit “0” indicates the first row in the batch. The numbering scheme is zero-based (due to its direct relationship to JSON)

Each entry is prefixed by “request.”

byAliLocator – 20170320

Name Required Notes
locations.N.trackingLabel No Client value for tracking batch row identity
locations.N.aliLocator. Yes Specific validly formatted AliLocator™. Exactly one of the three types below must be provided
locations.N.aliLocator.stringent.value Type 1 – PCIL in strict format of GSIL[SSIL].LUIL
locations.N.aliLocator.lenient.value Type 2 – PCIL in less strict format; i.e. first instance of valid GSIL is parsed and then first instances of SSIL and/or LUIL parsed from input string value
locations.N.aliLocator.componentized. Type 3 – Each PCIL component is provided in its own parameter
locations.N.aliLocator.componentized.gsil 12 digit GSIL value (required)
locations.N.aliLocator.componentized.ssil 3 digit SSIL value (optional)
locations.N.aliLocator.componentized.luil 10 digit LUIL value (optional)

Each entry is prefixed by “request.”

byStreetAddress – 20170320

Name Rqrd. Notes
defaults.country No* Required if not provided by at least one batch row entry – if provided, currently the only valid value is “USA”
locations.N. Specific validly formatted street address. Exactly one of the four types below must be provided (numbering scheme is zero based)
locations.N.trackingLabel No Client value for tracking batch row identity

Type 1

locations.N.singleLine.country No* Required if not provided by defaults.country – if provided, currently the only valid value is “USA”
locations.N.singleLine.line Yes Full address as single line; ex: 716 Lake Carolyn Pkwy Apt 331, Irving, Tx 75039-3988

Type 2

locations.N.doubleLine.country No* Required if not provided by defaults.country – if provided, currently the only valid value is “USA”
locations.N.doubleLine.lineBottom Yes Non-street parts of address; ex: Irving, Tx 75029-3988
locations.N.doubleLine.lineStreet Yes Street parts of address; ex: 716 Lake Carolyn Pkwy Apt 331

Type 3

locations.N.tripleLine.country No* Required if not provided by defaults.country – if provided, currently the only valid value is “USA”
locations.N.tripleLine.lineBottom Yes Non-street parts of address; ex: Irving, Tx 75029-3988
locations.N.tripleLine.lineStreetFirst Yes Primary street parts of address with secondary optional; ex: 716 Lake Carolyn Pkwy Apt 231
locations.N.tripleLine.lineStreetSecondary No Secondary street parts of address: ex: Apt 331 When secondary is provided both in lineStreetFirst and lineStreetSecondary, this value overrides whatever was provided in lineStreetFirst

Type 4

locations.N.componentized.country No* Required if not provided by defaults.country – if provided, currently the only valid value is “USA”
locations.N.componentized.postalCodePrimary No* Required if postalCode, city and stateProvinceRegionCode2 are not provided; ex: 75039
locations.N.componentized.postalCodeSecondary No Requires postalCodePrimary be provided; ex: 3988
locations.N.componentized.postalCode No* Required if postalCodePrimary, city and stateProvinceRegionCode2 are not provided; ex: 75039-3988
locations.N.componentized.stateProvinceRegionCode2 No* Required if postalCodePrimary, postalCode, stateProvinceRegionCodeName, and stateProvinceRegionCode are not provided; ex: Tx
locations.N.componentized.stateProvinceRegionCodeName No* Required if postalCodePrimary, postalCode, stateProvinceRegionCode2, and stateProvinceRegionCode are not provided; ex: Texas
locations.N.componentized.stateProvinceRegionCode No* Required if postalCodePrimary, postalCode, stateProvinceRegionCode2, and stateProvinceRegionCodeName are not provided; ex: Tex
locations.N.componentized.city No* Required if postalCodePrimary and postalCode are not provided
locations.N.componentized.neighborhood Planned for later use; i.e. when Mexico is implemented
locations.N.componentized.streetPrimary No* Required if street and streetSansSecondary are not provided – excludes both the street number and secondary; ex: Lake Carolyn Pkwy
locations.N.componentized.streetNumber No Requires streetPrimary be provided; ex: 716
locations.N.componentized.streetSecondaryDesignator No Requires streetPrimary, street or streetSansSecondary be provided; ex: Apt
locations.N.componentized.streetSecondaryValue No Requires streetSecondaryDesignator be provided; ex: 331
locations.N.componentized.street No* Required if streetPrimary and streetSansSecondary are not provided – may include both the street number and the secondary; ex: 716 Lake Carolyn Pkwy Apt 331
locations.N.componentized.streetSecondary No Requires street or streetSansSecondary be provided; ex: Apt 331
locations.N.componentized.streetSansSecondary No* Required if streetPrimary and street are not provided – may include the street number but not the secondary; ex: 716 Lake Carolyn Pkwy

 

Authentication

As this SaaS web-service is stateless, each request must provide authentication credentials. The authentication credentials may be provided via several different mechanisms:

  1. As an HTTPS OAuth header (also referred to as “out-of-band”)
  2. As clear text URI encoded input parameters (also referred to as “in-band”)
  3. As clear text POST parameters (in either the standard parameters or the JSON document)

Providing in-band authentication credentials is covered in section 2.1.1.2 in the “General” table with the transaction.clientCredentials.* input parameters.

Providing out-of-band authentication credentials is not covered in this document. The OAuth 1.0 standard is supported and has been tested using Chrome “Version 44.0.2403.157 m”.

Input Parameter Combinations

Parameters may be submitted via both embedded within the URL and within the associated POST buffer. If the same parameter appears in both places, the value of the one in the POST buffer overrides that of the one appearing embedded within the URL.

As there are no restrictions where parameters may be submitted, some SaaS client interaction designs might prefer to separate the “transaction.” prefixed parameters from the “request.” prefixed parameters.

As such, the following is a suggested SaaS client implementation pattern:

  1. Pass the (two) authentication parameters via OAuth 1.0 (so they never appear as clear text)

Note: The pair of authentication parameters must be both passed in the same way; i.e. if one is embedded within the URL, then the other must also be embedded within the URL. Authentication is designed to fail if the two parameters are separated by input parameter type.

  1. Pass the transaction (endpoint) parameters embedded within the URL
  2. Pass the request parameters in the POST buffer (as either an encoded parameter list or as a JSON document).

A concrete implementation of the suggested client implementation pattern might look like this:

  1. OAuth 1.0:

Encode the two authentication parameters

  1. URL (POST):

https://bamsaas.com/api?transaction.endPoint.name=byStreetAddress&transaction.endPoint.version=20170320&transaction.endPoint.kind=Payload&transaction.endPoint.format.output=JSON

  1. POST buffer:

Set as MIME type “application/json”.

Submit JSON (while the JSON “pretty” format is shown below, the JSON may also be sent in the “compact” format):

{
  "request": {
    "trackingLabel": "Parameters both in URL and POST JSON",
    "defaults": {
      "country": "USA"
    },
    "locations": [
      {
        "trackingLabel": "componentized.full.explicit",
        "componentized": {
          "full": {
            "explicit": {
              "optionCountry": "Usa",
              "postalCodePrimary": "75039",
              "optionPostalCodeSecondary": "3988",
              "stateProvinceRegionCode2": "Tx",
              "city": "Irving",
              "streetPrimary": "Lake Carolyn Pkwy",
              "optionStreetNumber": "716",
              "optionStreetSecondaryDesignator": "#",
              "optionStreetSecondaryValue": "231"
            }
          }
        }
      }
    ]
  }
}

It is possible to send the entire request through as just a JSON document (although passing authentication credentials this way is strongly discouraged), which might look something like this:

  1. URL (POST):

https://bamsaas.com/api

  1. POST buffer:

Set as MIME type “application/json”.

Submit JSON (while the JSON “pretty” format is shown below, the JSON may also be sent in the “compact” format):

{
  "transaction": {
    "clientCredentials": {
      "accessKey": "test.drive@assetlocationintelligence.com",
      "secretKey": "********"
    },
    "endPoint": {
      "name": "byStreetAddress",
      "version": "20170320",
      "kind": "payload",
      "format": {
        "output": "json"
      }
    }
  },
  "request": {
    "trackingLabel": "Parameters only in POST JSON",
    "defaults": {
      "country": "USA"
    },
    "locations": [
      {
        "trackingLabel": "componentized.full.explicit",
        "componentized": {
          "full": {
            "explicit": {
              "optionCountry": "Usa",
              "postalCodePrimary": "75039",
              "optionPostalCodeSecondary": "3988",
              "stateProvinceRegionCode2": "Tx",
              "city": "Irving",
              "streetPrimary": "Lake Carolyn Pkwy",
              "optionStreetNumber": "716",
              "optionStreetSecondaryDesignator": "#",
              "optionStreetSecondaryValue": "231"
            }
          }
        }
      }
    ]
  }
}

Input Models for byStreetAddress Endpoint

Conceptually, there are three different dimensions when specifying a particular street address entry to the byStreetAddress endpoint:

  1. Kind – required – the general parsing level of all the street address parameters
    1. SingleLine
    2. DoubleLine
    3. TripleLine
    4. Componentized
  2. Profile – optional – the search type for the address
    1. Full – attempts match on both the postal code and the named area (stateProvinceRegion and city)
    2. Partial – attempts match on only one of either the postal code or the named area (stateProvinceRegion and city)
  3. Clarity – optional – the specific parsing level of the individual parameters
    1. Explicit – each provided parameter is at its maximum parse level
    2. Melded – at least one input parameter needs to be parsed as it is the merging of two explicit parameters (ex: “Apt 231” appearing in streetSecondary, is parse-able into the two explicit parameters, streetSecondaryDesignator and streetSecondaryValue)

Every street address submitted is placed into a container conforming to these three dimensions. While the “kind” must be specified for each particular location’s street address parameters, if either the optional “profile” and/or “clarity” are not provided, they will be inferred from the parameters used.

These three dimensions, kind, profile and clarity, are utilized for both the parsing phase of the input parameters as well as deriving the street address quality metric during the response construction phase. This latter phase compares how well the input street address correlated to the found response candidate street address.

For the SingleLine, DoubleLine and TripleLine kinds, only the “clarity” level of “merged” is valid (as “explicit” doesn’t have any reasonable meaning except within the context of “componentized”).

Example request URLs

The examples below all use GET and URI encoded parameters.

Human readable HTML pages:

Direct request immediately returning JSON response:

Output

When the client submits a properly formed URL with sufficient input parameters, a well-formed response is generated and returned via the HTTP response. The only response format currently implemented is JSON (XML is planned).

JSON Response

If the JSON response is specified, the format of the JSON follows a specific pattern; a root object containing three sub-objects: transaction, request and response. The transaction sub-object is the same across all requests. It is used to facilitate specific transaction tracking and to enable faster technical support response times.

The request and response sub-objects will be unique to the endpoint (and possibly even version) specified in the request.

Example response JSON documents will be provided below (at 2.2.2).

Transaction

Appearing in all JSON responses, the transaction section provides the details of the specific interaction with the SaaS endpoint. Each name value in the tables below is assumed to be prefixed with “transaction.”.

transaction

Name Notes
client.trackingValue Client’s ID from credentials database (functioning email address) – is provided regardless of the client credentials input method used
client.ipV4 INET4 address (IPv4) of system calling this SaaS – assist for a client to locate the specific system calling the SaaS which is required when utilizing ALI-WS technical support)
endpoint.name Specific endpoint to process request – echos the request.endpoint.name parameter
endpoint.version Specific version of endpoint.name to process request – echos the request.endpoint.version parameter
endpoint.kind Specific kind of endpoint.name to process request – echos the request.endpoint.kind parameter
endpoint.format.inputs Specific type of input to process request – is automatically inferred and can be the values URL, POST and URL+POST
endpoint.format.output Specific type of output to process request – echos the request.endpoint.outputFormat parameter
uuid A unique ID assigned to this specific transaction in the archive – to quickly facilitate technical support activities
utcDateTimeStamp.inMillis Instant measured in milliseconds from the Java epoch of 1970-01-01T00:00:00Z
utcDateTimeStamp.formatted YYYYmmDDThhMMss.mmmZ (ex: 20150824T224227.987Z)
status.code Indication of the whole transaction – valid values are “SUCCESS” and “FAILURE”
status.description More fully expressed human readable meaning of status.code
generatedInMillis Total internal time spend by SaaS processing request

 

Request

There are subsections in each of the specific endpoint responses which are common between them.

common

Name Notes
request.trackingLabel Echoed in response.trackingLabel output parameter
request.defaults.country Echoed in response.defaults.country output parameter

There are also subsections specific to each particular endpoint.

unique – byAliLocator – 20170320

Name Notes
request.locations.N.trackingLabel Echoed in response.locations.N.trackingLabel output parameter
request.locations.N.aliLocator Echoed in response.locations.N.aliLocator output parameter

 

unique- byStreetAddress – 20170320

Name Notes
request.locations.N.representation The internal type to which the response.locations.* input parameters mapped – only appears if parsing successful
request.locations.N.values Echoed in response.locations.* input parameters – each parameter may be different following successful parsing
request.locations.N.parsingError The specific error which occurred while attempting to parse the request.locations.* input parameters – only appears if parsing failed

 

Response

There are subsections in each of the specific endpoint responses which are common between them. Each name value in the tables below is assumed to be prefixed with “response.”.

common

Name Notes
locations.N.
locations.N.trackingLabel Echos request.locations.0.trackingLabel input parameter
locations.N.status.
locations.N.status.code Indication of this specific batch row – valid values are “SUCCESS” and “FAILURE”
locations.N.status.description More fully expressed human readable meaning of status.code
locations.N.detail.
locations.N.detail.aliLocatorValue.
locations.N.detail.aliLocatorValue.implicit Default unique AliLocator™ for this structure and possible sub-unit; ex: SM0V4TGE2BP9.TVKKDGBYA5
locations.N.detail.aliLocatorValue.explicit Expanded AliLocator allowing specification of non-primary street; ex: indicating “Main Ave” as opposed to the newly changed name of “MLK Ave”; ex: SM0V4TGE2BP9[ULM].TVKKDGBYA5
locations.N.detail.aliLocatorValue.hasLuils.
locations.N.detail.aliLocatorValue.hasLuils.gsil If true, the structure identified by the GSIL contains LUILs
locations.N.detail.aliLocatorValue.hasLuils.ssil If true, the part of the structure identified by the GSIL specifying the SSIL contains LUILs
locations.N.detail.aliLocatorValue.hasLuils.luil If true, the structure identified by the GSIL and the local unit identified by the LUIL itself contains nested LUILs
locations.N.detail.streetAddress.
locations.N.detail.streetAddress.singleLine The per-field-USPS-standardized-and-formatted pipe (“|”) separated components of the resolved address for the specific structure and possible specific (sub-)unit
locations.N.detail.streetAddress.country Country containing structure; ex: USA
locations.N.detail.streetAddress.postalCode.
locations.N.detail.streetAddress.postalCode.primary Country specific primary part of postal code value; ex: for USA, this is the zip5
locations.N.detail.streetAddress.postalCode.secondary Country specific secondary part of postal code value; ex: for USA, this is the plusZip4
locations.N.detail.streetAddress.namedArea.
locations.N.detail.streetAddress.namedArea.stateProvinceRegionCode2 Country specific sub-area 2 character alphanumeric code; ex: for USA, this is the two letter state abbreviation – “TX” for Texas
locations.N.detail.streetAddress.namedArea.city Country specific city
locations.N.detail.streetAddress.namedArea.neighborhood Country specific neighborhood – unused for USA
locations.N.detail.streetAddress.street.
locations.N.detail.streetAddress.street.primary Country specific street with neither the street number (also called house number) prefix nor the street secondary values; for “123 Main St Ste 100”, it is the substring “Main St”
locations.N.detail.streetAddress.street.number Country specific street number – typically the prefix to street.primary
locations.N.detail.streetAddress.street.secondary
locations.N.detail.streetAddress.street.secondary.designator Country specific street secondary type; ex: “Ste” for suite
locations.N.detail.streetAddress.street.secondary.value Country specific street secondary value – typically a number
locations.N.detail.streetAddress.geohashes.N.
locations.N.detail.streetAddress.geohashes.N.kind The part of the AliLocator to which this geohash is related; values are “gsil”, “ssi”l and “luil”
locations.N.detail.streetAddress.geohashes.N.value The geohash representing the spatial point for the structure; more detail about this value can be found at http://geohash.org/site/tips.html
locations.N.detail.streetAddress.geohashes.N.centerCoordinate
locations.N.detail.streetAddress.geohashes.N.centerCoordinate.longitude The x (horizontal) part of the geographic coordinate representing the centroid of the structure
locations.N.detail.streetAddress.geohashes.N.centerCoordinate.latitude The y (vertical) part of the geographic coordinate representing the centroid of the structure
locations.N.detail.streetAddress.geohashes.N.accuracy Indicates the level of accuracy the geohash to the structure; values are APPROXIMATION, NEARBY and CENTROID – values appear in the order of least to most accurate

 

common – byAliLocator – 20170320

Name Notes
locations.N.inputDelta.equalsImplicit Is only false if response.locations.0.detail.aliLocator.implicit is different from request.locations.0.aliLocator.*
locations.N.inputDelta.equalsExplicit Is only false if response.locations.0.detail.aliLocator.explicit is different from request.locations.0.aliLocator.*
locations.N.inputDelta.isDeprecated Is only true if the request.locations.0.aliLocator.* has been deprecated and is no longer in use – ex: redundant AliLocators assigned to same structure

 

common – byStreetAddress – 20170320

Name Notes
locations.N.inputDelta.grade Street address quality metric measuring the degree to which the input matched the result found
locations.N.inputDelta.grade.letter Ranges from A+ to F based on standard grading scale. Directly correlates to number
locations.N.inputDelta.grade.number Ranges from 100 to 0 based on standard grading scale. Directly correlates to letter
locations.N.inputDelta.grade.causes Only appears if the grade.number is less than 100; describes the “differences” discovered between the input and the resulting address found
locations.N.inputDelta.grade.causes.N.cause Description of the deficit cause
locations.N.inputDelta.grade.causes.N.deficit The amount to deduct from the numeric grade
locations.N.inputDelta.grade.causes.N.type Only appearing if input was parseable to components, indicates omission or error of specific component; values are “missing” and “incorrect”

 

Example response JSON

For this byAliLocator URL:

https://bamsaas.com/api?transaction.endPoint.name=byAliLocator&transaction.endPoint.version=20170320&transaction.endPoint.kind=Payload&transaction.endPoint.format.output=JSON&transaction.clientCredentials.accessKey=test.drive@assetlocationintelligence.com&transaction.clientCredentials.secretKey=not.a.real.email.address&request.locations.0.trackingLabel=ClientAcctSystem-98765&request.locations.0.aliLocator.stringent.value=FMMPTEXARU87

…the following JSON is returned:

{
  "transaction": {
    "client": {
      "trackingValue": "test.drive@assetlocationintelligence.com",
      "ipV4": "72.181.215.2"
    },
    "endPoint": {
      "name": "byAliLocator",
      "version": "20170320",
      "kind": "payload",
      "format": {
        "inputs": "uri",
        "output": "json"
      }
    },
    "uuid": "dbc3b377-212d-11e7-b413-020a01f809ab",
    "utcDateTimeStamp": {
      "inMillis": 1492186650237,
      "formatted": "20170414T161730.237Z"
    },
    "status": {
      "code": "SUCCESS",
      "description": "Success"
    },
    "generatedInMillis": 10
  },
  "request": {
    "trackingLabel": "dbc3b377-212d-11e7-b413-020a01f809ab",
    "locations": [
      {
        "trackingLabel": "ClientAcctSystem-98765",
        "aliLocator": {
          "value": "FMMPTEXARU87",
          "type": "Stringent"
        }
      }
    ]
  },
  "response": {
    "locations": [
      {
        "trackingLabel": "ClientAcctSystem-98765",
        "status": {
          "code": "SUCCESS",
          "description": ""
        },
        "detail": {
          "aliLocatorValue": {
            "implicit": "FMMPTEXARU87",
            "explicit": "FMMPTEXARU87[ACY]",
            "hasLuils": {
              "gsil": false,
              "ssil": false
            }
          },
          "streetAddress": {
            "singleLine": "USA|75081|5103|Tx|Richardson||E Spring Valley Rd|520||",
            "country": "USA",
            "postalCode": {
              "primary": "75081",
              "secondary": "5103"
            },
            "namedArea": {
              "stateProvinceRegionCode2": "Tx",
              "city": "Richardson"
            },
            "street": {
              "primary": "E Spring Valley Rd",
              "number": "520"
            }
          },
          "geohashes": [
            {
              "kind": "gsil",
              "value": "9vg5rh2x7gf3e",
              "centerCoordinate": {
                "longitude": -96.72278207028285,
                "latitude": 32.939649943728
              },
              "accuracy": "CENTROID"
            }
          ]
        },
        "inputDelta": {
          "equalsImplicit": true,
          "equalsExplicit": false
        }
      }
    ]
  }
}

For this byStreetAddress URL:

https://bamsaas.com/api?transaction.endPoint.name=byStreetAddress&transaction.endPoint.version=20170320&transaction.endPoint.kind=Payload&transaction.endPoint.format.output=JSON&transaction.clientCredentials.accessKey=test.drive@assetlocationintelligence.com&transaction.clientCredentials.secretKey=not.a.real.email.address&request.locations.0.trackingLabel=ClientAcctSystem-98765&request.locations.0.componentized.country=USA&request.locations.0.componentized.postalCodePrimary=75039&request.locations.0.componentized.postalCodeSecondary=3988&request.locations.0.componentized.stateProvinceRegionCode2=TX&request.locations.0.componentized.city=Irving&request.locations.0.componentized.street=716+Lake+Carolyn+Pkwy&request.locations.0.componentized.streetSecondary=Apt+331

…the following JSON was returned:

{
  "transaction": {
    "client": {
      "trackingValue": "test.drive@assetlocationintelligence.com",
      "ipV4": "72.181.215.2"
    },
    "endPoint": {
      "name": "byStreetAddress",
      "version": "20170320",
      "kind": "payload",
      "format": {
        "inputs": "uri",
        "output": "json"
      }
    },
    "uuid": "2b958228-212e-11e7-b413-020a01f809ab",
    "utcDateTimeStamp": {
      "inMillis": 1492186784152,
      "formatted": "20170414T161944.152Z"
    },
    "status": {
      "code": "SUCCESS",
      "description": "Success"
    },
    "generatedInMillis": 48
  },
  "request": {
    "trackingLabel": "2b958228-212e-11e7-b413-020a01f809ab",
    "locations": [
      {
        "trackingLabel": "ClientAcctSystem-98765",
        "country": "USA",
        "representation": "componentized.profile_partial.ClarityMelded",
        "values": {
          "postalCodePrimary": "75039",
          "postalCodeSecondary": "3988",
          "stateProvinceRegionCode2": "TX",
          "city": "Irving",
          "street": "716 Lake Carolyn Pkwy",
          "streetSecondary": "Apt 331"
        }
      }
    ]
  },
  "response": {
    "locations": [
      {
        "trackingLabel": "ClientAcctSystem-98765",
        "status": {
          "code": "SUCCESS",
          "description": "Success"
        },
        "detail": {
          "aliLocatorValue": {
            "implicit": "SM0V4TGE2BP9.TVKKDGBYA5",
            "explicit": "SM0V4TGE2BP9[ULM].TVKKDGBYA5",
            "hasLuils": {
              "gsil": true,
              "ssil": true
            }
          },
          "streetAddress": {
            "singleLine": "USA|75039|3988|Tx|Irving||Lake Carolyn Pkwy|716|Apt|331",
            "country": "USA",
            "postalCode": {
              "primary": "75039",
              "secondary": "3988"
            },
            "namedArea": {
              "stateProvinceRegionCode2": "Tx",
              "city": "Irving"
            },
            "street": {
              "primary": "Lake Carolyn Pkwy",
              "number": "716",
              "secondary": {
                "designator": "Apt",
                "value": "331"
              }
            }
          },
          "geohashes": [
            {
              "kind": "gsil",
              "value": "9vg4fq9qv887e",
              "centerCoordinate": {
                "longitude": -96.93041991675273,
                "latitude": 32.86401600809768
              },
              "accuracy": "CENTROID"
            }
          ]
        },
        "inputDelta": {
          "grade": {
            "letter": "A+",
            "number": 100
          }
        }
      }
    ]
  }
}

Here is a prefilled HTML form with some of the various ways the byAliLocator Types 1 through 3 may be specified when referring to an apartment building; i.e. excluding specifying a specific apartment unit.

 

Here is a prefilled HTML form with some of the various ways the byAliLocator Types 1 through 3 may be used for referring to a specific subunit in an apartment building.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 1 may be specified when referring to an apartment building; i.e. excluding specifying a specific apartment unit.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 2 may be specified when referring to an apartment building; i.e. excluding specifying a specific apartment unit.

 

The prefilled HTML form for byStreetAddress Type 3 is essentially identical to Type 2 when there is no apartment unit being specified.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 4 may be specified explicitly when referring to an apartment building; i.e. excluding specifying a specific apartment unit.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 4 may be specified meldedly when referring to an apartment building; i.e. excluding specifying a specific apartment unit.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 1 may be used for referring to a specific subunit in an apartment building.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 1 may be used for referring to a specific subunit in an apartment building using the wildcard (#) for the street secondary designator.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 2 may be used for referring to a specific subunit in an apartment building.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 3 may be used for referring to a specific subunit in an apartment building.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 4 may be specified explicit-ly when referring to an apartment building; i.e. excluding specifying a specific apartment unit.

 

Here is a prefilled HTML form with some of the various ways the byStreetAddress Type 4 may be specified melded-ly when referring to an apartment building; i.e. excluding specifying a specific apartment unit.

 

Client Testing and Validation

The SaaS has three independently maintained environments for handling all stages of client software development. For most client development (+99%), only the SaaS production environment needs to be used (with the appropriate dev or test client credentials so as to avoid being transaction charged for using production).

It is important to favor the SaaS production environment as much as possible. The SaaS Dev and Test environments will not be reliable points for full testing due to how the AliLocator™ inventory is managed over time. In other words, all curation and reconciliation of an AliLocator and its associated data will only occur in the SaaS production environment. Those changes are then periodically propagated back to the test and dev environments. As such, any sort of client testing with previously unknown (to the SaaS production environment) street addresses against SaaS Test and Dev may result in inconsistent failures.

If/when the SaaS provider and a specific client need to co-develop some new functionality rapidly, then a more nuanced development strategy involving the SaaS Test (and possibly even the SaaS Development) environments may be used. When this occurs, it will require very careful coordination between the SaaS development team and the client’s development team to ensure all the “differences from SaaS production” are kept in mind. Details regarding the SaaS Test (and Dev) environments will be provided separate from this document if/when they are needed.

 

Client Design Assumptions

The client must be able to open an HTTPS connection to the SaaS server, submit standard HTTP URI encoded parameters, receive a response of MIME type “application/json” and close the connection to the SaaS server. Additionally, the client must be able to parse standard JSON to consume the response’s contents.

Given the endpoint.version design of the SaaS (described in 1.3), the client is isolated from any/all production related changes to request input parameters and/or response output format.

 

Glossary of Terms

GSIL

Acronym for Global Structure Identification Label. This is the 12 character internally checksummed value as the primary and only required part of a PCIL. The GSIL represent a unique building structure; ex: an apartment building. There is exactly one of these for each unique building. An example value for an apartment complex building is “SM0V4TGE2BP9”.

LUIL

Acronym for Local Unit Identification Label. This is the 10 character internally, and with its parent GSIL, checksummed value as the secondary part of a PCIL. The LUIL represents a unique subunit of the building structure; ex: a specific apartment in an apartment building. There can be many of these within a building identified by a GSIL. An example value for an apartment within apartment building “SM0V4TGE2BP9” is “TVKKDGBYA5”.

PCIL

Acronym for Place Composition Identification Label. This is an instance of a collection of a GSIL (required), SSIL (optional) and LUIL (optional) checksummed value which is used to compose a unique identifier as a key which points to a particular set of building characteristics. There can be many of these for a particular building identified by the same GSIL. An example of an apartment within apartment building “SM0V4TGE2BP9” is “SM0V4TGE2BP9[ULM].TVKKDGBYA5”.

SSIL

Acronym for Street Specifier Identification Label. This is the 3 character internally, and with its parent GSIL, checksummed value as the tertiary part of a PCIL.The SSIL represents a unique street of the building structure; ex: a specific apartment in an apartment building. There can be many of these next to a building identified by a GSIL. An example value for an apartment within apartment building SM0V4TGE2BP9 is “ULM”.


Copyright © 2015-2018 Precision Location Intelligence, Inc.

All rights reserved. No part of this document may be reproduced or copied in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval system without permission in writing from Precision Location Intelligence, Inc.. This document contains information that is considered business sensitive. While Precision Location Intelligence, Inc. may freely copy and distribute this material, all copies must remain in the possession Precision Location Intelligence, Inc.. Product names are trademarked by their respective companies.