Build a ``Place`` instance from the specified JSON object.


        @param payload: JSON representation of a place::

                {
                  "area_id": string,
                  "address": {
                    component_type: string,
                    ...
                  } \ [
                    {
                      "locale": string,
                      component_type: string,
                      ...
                    },
                    ...
                  ],
                  "category": string,
                  "contacts": [
                    [ name:string, value:string, is_primary:boolean ],
                    ...
                  ],
                  "cover_photo_id": string,
                  "cover_photo_url": string,
                  "boundaries": [ vertex, ... ],
                  "locale": string,
                  "location": coordinates,
                  "timezone": integer
                }

            where:

            * ``area_id`` (optional): identification of the geographic area
              where the place is located in.  This parameter is optional if the
              parameter ``address`` is passed.  Both ``area_id`` and ``address``
              can be passed to the function.  If this parameter is passed to the
              function, it takes precedence over any administrative division of
              the same level or larger that would be defined as part of the
              address components.

            * ``address`` (required): postal address of the place, composed of one
              or more address components, which textual information is written in
              the specified locale.  An address component is defined with a
              component type and its value.  The component type is a string
              representation of an item of the enumeration
              ``AddressComponentType``.

            * ``category_id`` (optional): category qualifying this place.

            * ``contacts`` (optional): list of properties such as e-mail
              addresses, phone numbers, etc., in respect of the electronic
              business card specification (vCard).  The contact information is
              represented by a list of tuples of the following form::

                  [ [ name:ContantPropertyName, value:string[, is_primary:boolean] ], ... ]

              where:

              * ``name`` (required): type of this contact information, which
                can be one of these standard names in respect of the electronic
                business card specification (vCard).

              * ``value`` (required): value of this contact information
                representing by a string, such as ``+84.01272170781``, the
                formatted value for a telephone number property.

              * ``is_primary`` (optional): indicate whether this contact
                information is the primary for this place.  By default, the first
                contact information of a given type is the primary of this place.


              * ``cover_photo_id``: identification of the cover photo of the place,
                if any defined.

              * ``cover_photo_url``: Uniform Resource Locator (URL) that specifies
                the location of the cover photo of the place, if any defined.  The
                client application can use this URL and append the query parameter
                ``size`` to specify a given pixel resolution of this photo, such as
                ``thumbnail``, ``small``, ``medium``, ``large``.

            * ``boundaries`` (optional): a collection of one or more polygons that
              delimit the topological space of the place.  All of the polygons are
              within the spatial reference system.  It corresponds to an array of
              vertices.  There must be at least three vertices. Each vertex is a
              tuple composed of a longitude, a latitude, and a altitude::

                [ longitude, latitude, altitude ]

              Note that the first and last vertices must not be identical; a
              polygon is "auto-closed" between the first and last vertices.

            * ``locale`` (required): locale of the textual information that
              describes this place.  A locale corresponds to a tag respecting RFC
              4646, i.e., a ISO 639-3 alpha-3 code element optionally followed by
              a dash character ``-`` and a ISO 3166-1 alpha-2 code (referencing
              the country that this language might be specific to).  For example:
              ``eng`` (which denotes a standard English), ``eng-US`` (which
              denotes an American English).

            * ``location`` (optional): geographic coordinates of the location of
              the place represented with the following JSON structure::

                  {
                    "accuracy": decimal
                    "altitude": decimal,
                    "latitude": decimal,
                    "longitude": decimal,
                  }

              where:

              * ``accuracy`` (optional): accuracy of the place's position in
                meters.

              * ``altitude`` (optional): altitude in meters of the place.

              * ``latitude`` (required): latitude-angular distance, expressed
                in decimal degrees (WGS84 datum), measured from the center of the
                Earth, of a point north or south of the Equator corresponding to
                the place's location.

              * ``longitude`` (required): longitude-angular distance,
                expressed in decimal degrees (WGS84 datum), measured from the
                center of the Earth, of a point east or west of the Prime
                Meridian corresponding to the place's location.

                .. note::

                   The parameter ``location`` is ignored when the parameter
                   ``boundaries`` is provided.  The platform computes the coordinates of
                   the geometric center (centroid) of the polygon representing the
                   boundaries of the place.  It corresponds to the arithmetic mean
                   ("average") position of all the points in the shape.

            * ``timezone`` (required): time zone at the place's location.  It is
              the difference between the time at this location and UTC
              (Coordinated Universal Time).  UTC is also known as GMT or
              Greenwich Mean Time or Zulu Time.

        @note: the name of the place corresponds to the address component
            ``recipient_name``.

        @return: a ``Place`` instance or ``None`` if the JSON payload is
            nil.

def from_json(payload):
        """
        Build a ``Place`` instance from the specified JSON object.


        @param payload: JSON representation of a place::

                {
                  "area_id": string,
                  "address": {
                    component_type: string,
                    ...
                  } \ [
                    {
                      "locale": string,
                      component_type: string,
                      ...
                    },
                    ...
                  ],
                  "category": string,
                  "contacts": [
                    [ name:string, value:string, is_primary:boolean ],
                    ...
                  ],
                  "cover_photo_id": string,
                  "cover_photo_url": string,
                  "boundaries": [ vertex, ... ],
                  "locale": string,
                  "location": coordinates,
                  "timezone": integer
                }

            where:

            * ``area_id`` (optional): identification of the geographic area
              where the place is located in.  This parameter is optional if the
              parameter ``address`` is passed.  Both ``area_id`` and ``address``
              can be passed to the function.  If this parameter is passed to the
              function, it takes precedence over any administrative division of
              the same level or larger that would be defined as part of the
              address components.

            * ``address`` (required): postal address of the place, composed of one
              or more address components, which textual information is written in
              the specified locale.  An address component is defined with a
              component type and its value.  The component type is a string
              representation of an item of the enumeration
              ``AddressComponentType``.

            * ``category_id`` (optional): category qualifying this place.

            * ``contacts`` (optional): list of properties such as e-mail
              addresses, phone numbers, etc., in respect of the electronic
              business card specification (vCard).  The contact information is
              represented by a list of tuples of the following form::

                  [ [ name:ContantPropertyName, value:string[, is_primary:boolean] ], ... ]

              where:

              * ``name`` (required): type of this contact information, which
                can be one of these standard names in respect of the electronic
                business card specification (vCard).

              * ``value`` (required): value of this contact information
                representing by a string, such as ``+84.01272170781``, the
                formatted value for a telephone number property.

              * ``is_primary`` (optional): indicate whether this contact
                information is the primary for this place.  By default, the first
                contact information of a given type is the primary of this place.


              * ``cover_photo_id``: identification of the cover photo of the place,
                if any defined.

              * ``cover_photo_url``: Uniform Resource Locator (URL) that specifies
                the location of the cover photo of the place, if any defined.  The
                client application can use this URL and append the query parameter
                ``size`` to specify a given pixel resolution of this photo, such as
                ``thumbnail``, ``small``, ``medium``, ``large``.

            * ``boundaries`` (optional): a collection of one or more polygons that
              delimit the topological space of the place.  All of the polygons are
              within the spatial reference system.  It corresponds to an array of
              vertices.  There must be at least three vertices. Each vertex is a
              tuple composed of a longitude, a latitude, and a altitude::

                [ longitude, latitude, altitude ]

              Note that the first and last vertices must not be identical; a
              polygon is "auto-closed" between the first and last vertices.

            * ``locale`` (required): locale of the textual information that
              describes this place.  A locale corresponds to a tag respecting RFC
              4646, i.e., a ISO 639-3 alpha-3 code element optionally followed by
              a dash character ``-`` and a ISO 3166-1 alpha-2 code (referencing
              the country that this language might be specific to).  For example:
              ``eng`` (which denotes a standard English), ``eng-US`` (which
              denotes an American English).

            * ``location`` (optional): geographic coordinates of the location of
              the place represented with the following JSON structure::

                  {
                    "accuracy": decimal
                    "altitude": decimal,
                    "latitude": decimal,
                    "longitude": decimal,
                  }

              where:

              * ``accuracy`` (optional): accuracy of the place's position in
                meters.

              * ``altitude`` (optional): altitude in meters of the place.

              * ``latitude`` (required): latitude-angular distance, expressed
                in decimal degrees (WGS84 datum), measured from the center of the
                Earth, of a point north or south of the Equator corresponding to
                the place's location.

              * ``longitude`` (required): longitude-angular distance,
                expressed in decimal degrees (WGS84 datum), measured from the
                center of the Earth, of a point east or west of the Prime
                Meridian corresponding to the place's location.

                .. note::

                   The parameter ``location`` is ignored when the parameter
                   ``boundaries`` is provided.  The platform computes the coordinates of
                   the geometric center (centroid) of the polygon representing the
                   boundaries of the place.  It corresponds to the arithmetic mean
                   ("average") position of all the points in the shape.

            * ``timezone`` (required): time zone at the place's location.  It is
              the difference between the time at this location and UTC
              (Coordinated Universal Time).  UTC is also known as GMT or
              Greenwich Mean Time or Zulu Time.

        @note: the name of the place corresponds to the address component
            ``recipient_name``.

        @return: a ``Place`` instance or ``None`` if the JSON payload is
            nil.
        """
        return payload and \
            Place([ (float(lon), float(lat), float(alt)) for (lon, lat, alt) in payload['boundaries']]
                       if payload.get('boundaries') else GeoPoint.from_json(payload['location']),
                address=payload.get('address') and (
                    Place.__parse_address__(payload['address']) if isinstance(payload['address'], dict)
                        else [ Place.__parse_address__(address) for address in payload['address'] ]),
                category_id=cast.string_to_uuid(payload.get('category_id')),
                area_id=cast.string_to_uuid(payload.get('area_id')),
                contacts=payload.get('contacts') and [
                        (cast.string_to_enum(contact[0], ContactPropertyName), # name
                         contact[1],                                           # value
                         contact[2] if len(contact) >= 3 else None,            # is_primary
                         contact[3] if len(contact) == 4 else None)            # is_verified
                    for contact in payload['contacts'] ],
                cover_photo_id=cast.string_to_uuid(payload.get('cover_photo_id')),
                cover_photo_url=payload.get('cover_photo_url'),
                locale=cast.string_to_locale(payload.get('locale')) and DEFAULT_LOCALE,
                object_status=payload.get("object_status"),
                place_id=cast.string_to_uuid(payload.get('place_id')),
                timezone=payload.get('timezone'))