{
  "swagger": "2.0",
  "info": {
    "title": "Address API",
    "description": "API for address, address suggestions, autocomplete, and address validation.",
    "version": "v1"
  },
  "tags": [
    {
      "name": "AddressService"
    }
  ],
  "basePath": "/address/v1",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/address_books/{address_book_id}/contacts": {
      "get": {
        "summary": "Lists contacts saved in the address book.",
        "operationId": "AddressService_ListContacts",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/addressListContactsResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "address_book_id",
            "description": "The resource id of the set of contacts to retrieve.\nTypically this is the customer ID.",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "[^/]+"
          },
          {
            "name": "country_code",
            "description": "Country code defined as ISO 3166-1 alpha-2, country code of the addresses.",
            "in": "query",
            "required": false,
            "type": "string"
          }
        ],
        "tags": [
          "AddressService"
        ]
      },
      "post": {
        "summary": "Create a new contact in the address book.",
        "description": "contact.contact_id is optional and, if provided, will be used as the contact ID. If not provided,\na new unique ID will be generated.\n\nNote that contacts in the address book needs to be unique. Creating a contact with the same\naddress as another contact will result in an error.",
        "operationId": "AddressService_CreateContact",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1alphaaddressContact"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "address_book_id",
            "description": "The resource id of the address book the contact should belong to.\nTypically this is the customer ID.",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "[^/]+"
          },
          {
            "name": "contact",
            "description": "The contact to create.",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/v1alphaaddressContact",
              "required": [
                "contact"
              ]
            }
          }
        ],
        "tags": [
          "AddressService"
        ]
      }
    },
    "/address_books/{address_book_id}/contacts/{contact.contact_id}": {
      "patch": {
        "summary": "Update an existing contact in the address book.",
        "description": "contact.contact_id is extracted from the path and does not need to be set in the request body.\n\nNote that contacts in the address book needs to be unique. Updating a contact to have the same\naddress as another contact will result in an error.",
        "operationId": "AddressService_UpdateContact",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/v1alphaaddressContact"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "address_book_id",
            "description": "The resource id of the address book the contact belongs to.\nTypically this is the customer ID.",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "[^/]+"
          },
          {
            "name": "contact.contact_id",
            "description": "The identifier of the contact.",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "[^/]+"
          },
          {
            "name": "contact",
            "description": "The contact to update.",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "properties": {
                "address": {
                  "$ref": "#/definitions/addressAddress",
                  "description": "The physical address of the contact."
                },
                "email": {
                  "type": "string",
                  "description": "The email address of the contact."
                },
                "phone_number": {
                  "$ref": "#/definitions/ContactPhoneNumber",
                  "description": "The phone number of the contact, including region and optional extension."
                },
                "name": {
                  "type": "string",
                  "description": "Full name associated with the contact."
                },
                "first_name": {
                  "type": "string",
                  "description": "First name associated with the contact."
                },
                "last_name": {
                  "type": "string",
                  "description": "Last name associated with the contact."
                },
                "national_id_number": {
                  "type": "string",
                  "description": "National ID number associated with the contact."
                },
                "company_name": {
                  "type": "string",
                  "description": "Company name associated with the contact."
                },
                "vat": {
                  "type": "string",
                  "description": "VAT number associated with the contact."
                },
                "customs_number": {
                  "type": "string",
                  "description": "Customs number associated with the contact."
                }
              },
              "title": "The contact to update.",
              "required": [
                "address",
                "contact"
              ]
            }
          }
        ],
        "tags": [
          "AddressService"
        ]
      }
    },
    "/address_books/{address_book_id}/contacts/{contact_id}": {
      "delete": {
        "summary": "Delete a contact from the address book.",
        "operationId": "AddressService_DeleteContact",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "type": "object",
              "properties": {}
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "address_book_id",
            "description": "The resource id of the address book the contact belongs to.\nTypically this is the customer ID.",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "[^/]+"
          },
          {
            "name": "contact_id",
            "description": "The contact ID to delete.",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "[^/]+"
          }
        ],
        "tags": [
          "AddressService"
        ]
      }
    },
    "/suggestions": {
      "get": {
        "summary": "Lists address suggestions based on customer input and other contextual information.",
        "operationId": "AddressService_ListSuggestions",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/addressListSuggestionsResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "customer_search_input",
            "description": "Customer input for address search.",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "country_code",
            "description": "Country code defined as ISO 3166-1 alpha-2, customer's country code.",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "locales",
            "description": "Locales list defined as lc-CC compliant with ISO 3166-1, in order of preference(first supported one will be chosen).",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            },
            "collectionFormat": "multi"
          },
          {
            "name": "provider",
            "description": "Data provider to be used for suggestions. If not specified, the default one will be used.\n\n - UNSPECIFIED: If the provider is unspecified or unknown, the default one will be used.",
            "in": "query",
            "required": false,
            "type": "string",
            "enum": [
              "UNSPECIFIED",
              "GOOGLE_MAPS",
              "LOQATE"
            ],
            "default": "UNSPECIFIED"
          },
          {
            "name": "provider_session_token",
            "description": "Identifier for customer session, to be passed to the data provider for better address suggestions quality.\nWhen no provider is specified, a new session will be started for each request.",
            "in": "query",
            "required": false,
            "type": "string"
          },
          {
            "name": "container_id",
            "description": "When customer selects a suggestion container from previous suggestions list request,\npass its container_id here to get more detailed suggestions.",
            "in": "query",
            "required": false,
            "type": "string"
          }
        ],
        "tags": [
          "AddressService"
        ]
      }
    },
    "/suggestions/{id}:convert": {
      "get": {
        "summary": "Convert an address by suggestion name to address.",
        "operationId": "AddressService_ConvertSuggestion",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/addressConvertSuggestionResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "description": "The resource name of the suggestion to retrieve.",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "[^/]+"
          },
          {
            "name": "locales",
            "description": "Locales list defined as lc-CC compliant with ISO 3166-1, in order of preference(first supported one will be chosen).",
            "in": "query",
            "required": false,
            "type": "array",
            "items": {
              "type": "string"
            },
            "collectionFormat": "multi"
          },
          {
            "name": "provider",
            "description": "Data provider to be used for suggestions. If not specified, the default one will be used.\n\n - UNSPECIFIED: If the provider is unspecified or unknown, the default one will be used.",
            "in": "query",
            "required": false,
            "type": "string",
            "enum": [
              "UNSPECIFIED",
              "GOOGLE_MAPS",
              "LOQATE"
            ],
            "default": "UNSPECIFIED"
          },
          {
            "name": "provider_session_token",
            "description": "Identifier for customer session, to be passed to the data provider for better address suggestions quality.\nWhen not provided, a new session will be started for each request.",
            "in": "query",
            "required": false,
            "type": "string"
          }
        ],
        "tags": [
          "AddressService"
        ]
      }
    },
    "/validate": {
      "post": {
        "summary": "ValidateAddress validates the correctness of a provided address. Returns a suggestion if an address is not correct.",
        "operationId": "AddressService_ValidateAddress",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/addressValidateAddressResponse"
            }
          },
          "default": {
            "description": "An unexpected error response.",
            "schema": {
              "$ref": "#/definitions/rpcStatus"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "description": "Request message for validating an address.",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/addressValidateAddressRequest"
            }
          }
        ],
        "tags": [
          "AddressService"
        ]
      }
    }
  },
  "definitions": {
    "AddressSuggestionAddressComponentId": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "ADDRESS_LINES",
        "ADDRESS_LINES_2",
        "CITY",
        "POSTAL_CODE",
        "COUNTRY",
        "REGION",
        "NAME",
        "STREET",
        "STREET_NUMBER",
        "APARTMENT_NUMBER",
        "EMAIL",
        "PHONE_NUMBER",
        "FIRST_NAME",
        "LAST_NAME",
        "BUILDING_NAME"
      ],
      "default": "UNKNOWN"
    },
    "ContactPhoneNumber": {
      "type": "object",
      "properties": {
        "country_code": {
          "type": "string",
          "description": "\nThe country code where the delivery will occur (ISO 3166-1 alpha-2)."
        },
        "number": {
          "type": "string",
          "description": "The main phone number, formatted as per the region's conventions."
        },
        "extension": {
          "type": "string",
          "description": "An optional phone number extension."
        }
      },
      "description": "A phone number, including region and optional extension.",
      "required": [
        "country_code",
        "number"
      ]
    },
    "ValidateAddressResponseAddressSuggestion": {
      "type": "object",
      "properties": {
        "address": {
          "$ref": "#/definitions/addressAddress"
        },
        "invalid_components": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/AddressSuggestionAddressComponentId"
          }
        }
      },
      "required": [
        "address",
        "invalid_components"
      ]
    },
    "ValidateAddressResponseVerifyResultType": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "VALID",
        "INVALID"
      ],
      "default": "UNKNOWN"
    },
    "addressAddress": {
      "type": "object",
      "properties": {
        "country_code": {
          "type": "string",
          "description": "\nRefers to a ISO-3166 alpha 2 country code."
        },
        "region_code": {
          "type": "string",
          "description": "Refers to a first-level administrative subdivision code (ISO-3166-2) without the country_code prefix.\nExample: region for Washington, D.C. = `DC` (from `US-DC`).\nException: for some countries (e.g. Mexico, Hong Kong) we store the subdivision name instead.\nExample: region for Hong Kong = `Kowloon`."
        },
        "subregion_code": {
          "type": "string",
          "description": "Refers to a second-level administrative subdivision below the region (ISO-3166-2), without the country_code prefix.\nExample: region for Washington State = `WA` (from `US-WA`), subregion for King County = `033` (from `US-WA-033`).\nException: for some countries (e.g. Mexico, Hong Kong) we store the subdivision name instead.\nExample: subregion within Hong Kong/Kowloon = `Tsim Sha Tsui`."
        },
        "postal_code": {
          "type": "string",
          "description": "Refers to a postal code or zipcode."
        },
        "city": {
          "type": "string",
          "description": "Refers to a city, postal_town or locality."
        },
        "address_lines": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of strings, each a part of the address, e.g., street name, street number, building name, floor."
        },
        "street": {
          "type": "string",
          "description": "Street name of the address."
        },
        "street_number": {
          "type": "string",
          "description": "Street number of the address."
        },
        "apartment_number": {
          "type": "string",
          "description": "Apartment number of the address."
        },
        "building_name": {
          "type": "string",
          "description": "Building name of the address."
        },
        "floor_number": {
          "type": "string",
          "description": "Floor number of the address."
        },
        "po_box_id": {
          "type": "string",
          "description": "PO Box identifier of the address."
        },
        "name": {
          "type": "string",
          "description": "Full name associated with the address, for example company name."
        },
        "care_of": {
          "type": "string",
          "description": "Care of information associated with the address."
        },
        "coordinates": {
          "$ref": "#/definitions/addressCoordinates",
          "description": "Geolocation of the given address."
        }
      },
      "description": "Represents an address suitable for delivery.",
      "required": [
        "country_code"
      ]
    },
    "addressConvertSuggestionResponse": {
      "type": "object",
      "properties": {
        "address": {
          "$ref": "#/definitions/addressAddress"
        }
      },
      "description": "Response message for converted suggestion."
    },
    "addressCoordinates": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "format": "double",
          "description": "The latitude in degrees. Must be within the range -90.0 to +90.0, inclusive."
        },
        "lng": {
          "type": "number",
          "format": "double",
          "description": "The longitude in degrees. Must be within the range -180.0 to +180.0, inclusive."
        }
      },
      "description": "Represents a latitude/longitude pair.\nUnless specified otherwise, this must conform to the WGS84 standard.\nValues must be within normalized ranges.",
      "required": [
        "lat",
        "lng"
      ]
    },
    "addressListContactsResponse": {
      "type": "object",
      "properties": {
        "address_book_id": {
          "type": "string",
          "description": "The resource id of the address book of which to list contacts for.\nTypically this is the customer ID."
        },
        "contacts": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/v1alphaaddressContact"
          },
          "description": "A list of contacts in the address book."
        }
      },
      "description": "Response message for listing customer saved contacts."
    },
    "addressListSuggestionsResponse": {
      "type": "object",
      "properties": {
        "suggestions": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/addressSuggestion"
          },
          "description": "A list of address suggestions based on the request."
        }
      }
    },
    "addressProviderId": {
      "type": "string",
      "enum": [
        "UNSPECIFIED",
        "GOOGLE_MAPS",
        "LOQATE"
      ],
      "default": "UNSPECIFIED",
      "description": "External data provider for the suggestions and addresses.\n\n - UNSPECIFIED: If the provider is unspecified or unknown, the default one will be used."
    },
    "addressSuggestion": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The identifier of the suggestion.\nUsed to translate the suggestion into a full address in convert api."
        },
        "container_id": {
          "type": "string",
          "description": "Identifier of the group of suggestions (eg \"London, Tower Bridge Rd\").\nUsed to fetch more details about the suggestion in ListSuggestions."
        },
        "display_line_1": {
          "type": "string",
          "description": "Display line of the suggested address.\n\nExample for simple address:\n  display_line_1=\"1 Lanark Road\"\n  display_line_2=\"London W9 1DD\"\n\nExample for a container of addresses:\n  display_line_1=\"Landmann Way\"\n  display_line_2=\"London SE14 - 38 Addresses\""
        },
        "display_line_2": {
          "type": "string"
        },
        "provider": {
          "$ref": "#/definitions/addressProviderId"
        }
      },
      "description": "A Suggestion represents address suggestion returned by an address autocomplete service.",
      "required": [
        "container_id",
        "display_line_1",
        "provider"
      ]
    },
    "addressValidateAddressRequest": {
      "type": "object",
      "properties": {
        "address": {
          "$ref": "#/definitions/addressAddress",
          "description": "Address to be validated."
        },
        "provider": {
          "$ref": "#/definitions/addressProviderId",
          "description": "ProviderId is the ID of the data provider to be used for validation.\nIf not specified, the default one will be used."
        },
        "locales": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Locales list defined as lc-CC compliant with ISO 3166-1,\nin order of preference - the first supported one will be chosen.\nIf not specified, the default locale will be used.\nFor `Google` it is \"en-US\".\n`Loqate` does not use locales."
        }
      },
      "description": "Request message for validating an address.",
      "required": [
        "address"
      ]
    },
    "addressValidateAddressResponse": {
      "type": "object",
      "properties": {
        "result": {
          "$ref": "#/definitions/ValidateAddressResponseVerifyResultType",
          "description": "VerifyResultType indicates whether the address is valid or not."
        },
        "suggestion": {
          "$ref": "#/definitions/ValidateAddressResponseAddressSuggestion",
          "description": "AddressSuggestion provides a suggested address if the original address is invalid."
        }
      },
      "description": "Response message for validating an address.",
      "required": [
        "result"
      ]
    },
    "protobufAny": {
      "type": "object",
      "properties": {
        "@type": {
          "type": "string"
        }
      },
      "additionalProperties": {}
    },
    "rpcStatus": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/protobufAny"
          }
        }
      }
    },
    "v1alphaaddressContact": {
      "type": "object",
      "properties": {
        "contact_id": {
          "type": "string",
          "description": "The identifier of the contact."
        },
        "address": {
          "$ref": "#/definitions/addressAddress",
          "description": "The physical address of the contact."
        },
        "email": {
          "type": "string",
          "description": "The email address of the contact."
        },
        "phone_number": {
          "$ref": "#/definitions/ContactPhoneNumber",
          "description": "The phone number of the contact, including region and optional extension."
        },
        "name": {
          "type": "string",
          "description": "Full name associated with the contact."
        },
        "first_name": {
          "type": "string",
          "description": "First name associated with the contact."
        },
        "last_name": {
          "type": "string",
          "description": "Last name associated with the contact."
        },
        "national_id_number": {
          "type": "string",
          "description": "National ID number associated with the contact."
        },
        "company_name": {
          "type": "string",
          "description": "Company name associated with the contact."
        },
        "vat": {
          "type": "string",
          "description": "VAT number associated with the contact."
        },
        "customs_number": {
          "type": "string",
          "description": "Customs number associated with the contact."
        }
      },
      "description": "Contact represents generic contact information.",
      "required": [
        "address"
      ]
    }
  },
  "securityDefinitions": {
    "Authorization": {
      "type": "apiKey",
      "name": "authorization",
      "in": "header"
    }
  },
  "security": [
    {
      "Authorization": []
    }
  ]
}