def get_item_from_response( self, name_IN ):

        '''
        Accepts name of OpenCalais entity (a URL string).  Retrieves the json
            object for that entity from the response.  If not found, returns
            None.
        '''
        
        # return reference
        json_OUT = None
        
        # declare variables
        json_response_root = None
        
        # get JSON response root.
        json_response_root = self.get_json_response_object()

        # get property, default to None if not present.
        json_OUT = JSONHelper.get_json_object_property( json_response_root, name_IN, None )
        
        return json_OUT
    def set_json_response_object( self, json_object_IN ):
        
        '''
        Accepts JSON response object (name-value pairs) from call to OpenCalais
           REST API.  Stores it internally, then parses it and break out pieces
           so it is easier to work with.
        '''
        
        # return reference
        instance_OUT = None
        
        # declare variables
        me = "set_json_response_object"
        my_logger = None
        json_string = ""
        response_json_root = None
        item_counter = -1
        current_key = ""
        current_object = None
        current_type = ""
        current_type_group = ""
        doc_object = None
        current_status = ""
        
        # get logger
        my_logger = self.get_logger()
        
        # first, remind myself what the JSON looks like.
        #json_string = JSONHelper.pretty_print_json( json_object_IN )
        #my_logger.debug( "In " + me + ": outputting whole JSON document:" )
        #my_logger.debug( json_string )
        
        # store JSON response in "response_json_root" variable.
        response_json_root = json_object_IN
        
        # loop over the list of top-level things.  It should be a set of
        #    name-value pairs where the value is another structured JSON object.
        for item_counter, current_key in enumerate( response_json_root ):
        
            # grab JSON for the key.
            current_object = response_json_root[ current_key ]
            
            # get type group
            current_type_group = JSONHelper.get_json_object_property( current_object, self.JSON_NAME_ITEM_TYPE_GROUP )
            
            # get current entity type.
            current_type = JSONHelper.get_json_object_property( current_object, self.JSON_NAME_ITEM_TYPE )
            
            if ( self.DEBUG_FLAG == True ):

                # log it.
                my_logger.debug( "In " + me + ": #" + str( item_counter ) + " (type group: " + str( current_type_group ) + "; type: " + str( current_type ) + ") = " + current_key )
                
            #-- END DEBUG --#
            
            # if doc, store the doc off in separate reference for easy access.
            if ( current_key == self.JSON_NAME_DOC ):
            
                # store off the doc.
                self.set_doc( current_object )
                
                # output, just to make sure I have what I think I have.
                #json_string = JSONHelper.pretty_print_json( current_object )
                #my_logger.debug( "In " + me + ": outputting JSON \"doc\" object:" )
                #my_logger.debug( json_string )
            
            #-- END check to see if "doc" JSON --#
            
            # add to dict of type groups to items
            current_status = self.add_item_to_type_group_dict( current_key, current_object )
            
            if ( self.DEBUG_FLAG == True ):

                my_logger.debug( "In " + me + ": added to type group map: " + current_status )
                
            #-- END DEBUG --#
            
            # add to dict of types to items
            current_status = self.add_item_to_type_dict( current_key, current_object )
        
            if ( self.DEBUG_FLAG == True ):

                my_logger.debug( "In " + me + ": added to type map: " + current_status )

            #-- END DEBUG --#


        #-- END loop over top-level keys in JSON --#
        
        # store root in instance variable
        self.json_response_object = response_json_root
        instance_OUT = self.json_response_object
        
        if ( self.DEBUG_FLAG == True ):

            # try retrieving doc entity directly from root element.
            doc_object = self.get_item_from_response( self.JSON_NAME_DOC )
    
            # output, just to make sure I have what I think I have.
            json_string = JSONHelper.pretty_print_json( doc_object )
            my_logger.debug( "In " + me + ": outputting JSON \"doc\" object from lookup:" )
            my_logger.debug( json_string )
        
        #-- END DEBUG --#
        
        return instance_OUT

    #-- END method set_json_response_object() --#


#-- END class OpenCalaisV2ApiResponse --#
 def add_item_to_type_group_dict( self, item_id_IN, item_IN ):
     
     '''
     Accepts item.  Gets type group from inside the item.  Looks for group
        type in type_group_to_items_dict.  If present, retrieves associated,
        dictionary (item ID to item map), adds item.  If not, makes dict,
        adds item to dict, adds dict to type group dict mapped to group type.
     If success, returns item type group to which the item was added.  If
        error returns non-empty string describing it, preceded by
        self.STATUS_ERROR_PREFIX.
     '''
     
     # return reference
     status_OUT = ""
     
     # declare variables
     the_dict = None
     item_type_group = ""
     nested_dict = None
     
     # get dictionary
     the_dict = self.type_group_to_items_dict
     
     # get item's type_group
     item_type_group = JSONHelper.get_json_object_property( item_IN, self.JSON_NAME_ITEM_TYPE_GROUP )
     
     # got one?
     if item_type_group is not None:
     
         # got a group.  Is it in the dict?
         if item_type_group in the_dict:
         
             # it is in the dict - get nested dictionary
             nested_dict = the_dict[ item_type_group ]
             
             # add the item to the nested dictionary.
             nested_dict[ item_id_IN ] = item_IN
         
         else:
         
             # not there yet.  create a dictionary.
             nested_dict = {}
             
             # add the item
             nested_dict[ item_id_IN ] = item_IN
             
             # nest the dictionary.
             the_dict[ item_type_group ] = nested_dict
         
         #-- END check to see if type group is in the dictionary --#
         
         status_OUT = item_type_group
     
     else:
     
         # no group.
         status_OUT = self.STATUS_ERROR_PREFIX + "No type group in item."
     
     #-- END check to see if we have a type group --#
     
     return status_OUT