Address

Familiarize yourself with particulars of the address endpoint.

Description

An address refers to a specific location or designation that helps to identify and locate a particular place, object or entity. The concept of an address can apply to various contexts, including physical locations and digital spaces.


Add address

To onboard data to the platform below field specifications are available:

POST Request: {{BASE_URL}}/address

Field attributes

FieldTypeDescription
additionalInformationstringAdditional information that can not be displayed in the other attributes such as Building, Door Nr. etc.;minLength: 1maxLength: 500
addressIdstringUnique identifier either coming from previous system otherwise it needs to be defined;minLength: 1maxLength: 50 (mandatory)
apartmentOrUnitstringUnit number;minLength: 1 maxLength: 50
citystringAny official settlement including cities, towns, villages, hamlets, localities, etc;minLength:1 maxLength: 100 (mandatory)
countrystring enumSovereign nations and their dependent territories, anything with an ISO-3166 code;AF, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CD, CG, CK, CR, HR, CU, CW, CY, CZ, CI, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, MK, RO, RU, RW, RE, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UM, US, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, AX (mandatory)
districtstringBoroughs or districts within a city that serve some official purpose;minLength: 1maxLength: 50
eventTypestring enumType of the event as specific domain event ; AddressAdded, AddressUpdated
extensionDatajsonExtension data for storing any custom data
geoCoordinatesstringInformation about geographic data to enable the use of common locations of geographic features, imagery, and observation within a common geographic framework;Has 4 subsections with 1 mandatory field
geoCoordinateIdstringUnique identifier either coming from previous system otherwise it needs to be defined;minLength: 1maxLength: 50 (mandatory)
coordinateReferenceSystemstringSpecific coordinate reference system used; minLength: 1maxLength: 50
latitudenumberLatitude coordinate in case of geographic coordinates
longitudenumberLongitude coordinate in case of geographic coordinates
houseNumberstringHouse number of the street;minLength: 1 maxLength: 50
postalCodestringPostal codes used for mail sorting;minLength: 1maxLength: 15
stateProvincePrefecturestringFirst-level administrative division, depending on the continent or country if might be named differently;minLength: 1 maxLength: 50
streetNamestringName of the street;minLength: 1 maxLength: 150
typestring enumType of address;Primary, Other (mandatory)

Sample payload

[
    {
        "addressId": "{{addressUID}}",
        "additionalInformation": "Best address",
        "stateProvincePrefecture": "Berlin",
        "type": "Primary",
        "eventType": "AddressAdded",
        "country": "DE",
        "postalCode": "10369",
        "city": "Berlin"
        "streetName": "Alfred Jung Str. 12",
        "extensionData": {
            "language": "German",
            "timeZone": "IST"
        },
        "geoCoordinates": [
            {
                "geoCoordinateId": "{{$randomUUID}}",
                "latitude": 52.490659145197235,
                "longitude": 13.376379206244852
            }
        ]

In above sample payloadaddressIds can be a random string based on a customer’s requirement.

  • Once we the request is passed, a batchID will be generated (asynchronous API).
  • In case the addressID is not used anywhere, then status of this entity will be in failed state.
  • in case it is used by any site or building, the status will get completed.

Update address

Update Address is a post request, too. You can update any fields based on your requirements.

POST Request:{{BASE_URL}}/site

Sample payload

[
    {
        "addressId": "{{addressUID}}",
        "additionalInformation": "Best address",
        "stateProvincePrefecture": "Berlin",
        "type": "Primary",
        "eventType": "AddressUpdated",
        "country": "DE",
        "postalCode": "10369",
        "city": "Berlin"
        "streetName": "Alfred Jung Str. 12",
        "extensionData": {
            "language": "German",
            "timeZone": "IST"
        },
        "geoCoordinates": [
            {
                "geoCoordinateId": "{{$randomUUID}}",
                "latitude": 52.490659145197235,
                "longitude": 13.376379206244852
            }
        ]

View address status

Based on the batchID generated when on-boarding an address, you can GET the batch of the on-boarded address via the below mentioned request.

GET Request:{{BASE_URL}}/batch/{id}/inbound

Via this request, you can update yourself about the data onboarding progress of this entity.

  • In case this address is used in any other site or building it will get completed.
  • In case the addressID used here is not used in any other entity, this address will remain in a failed state.