org.opensextant.data.Geocoding Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of opensextant-xponents-core Show documentation
An information extraction toolkit focused on geography and temporal entities
There is a newer version: 3.7.3
Show newest version
/*
 *
 * Copyright 2012-2013 The MITRE Corporation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~|
//
// _____                                ____                     __                       __
///\  __`\                             /\  _`\                  /\ \__                   /\ \__
//\ \ \/\ \   _____      __     ___    \ \,\L\_\      __   __  _\ \ ,_\     __       ___ \ \ ,_\
// \ \ \ \ \ /\ '__`\  /'__`\ /' _ `\   \/_\__ \    /'__`\/\ \/'\\ \ \/   /'__`\   /' _ `\\ \ \/
//  \ \ \_\ \\ \ \L\ \/\  __/ /\ \/\ \    /\ \L\ \ /\  __/\/>  precision  = 5000 (m)
 * suggests your geocoding around point (Y,X) has an error of 5 KM.
 * 
 * @author Marc C. Ubaldino, MITRE, ubaldino at mitre dot org
 */
public interface Geocoding extends LatLon {

    //-------------------
    // High level flags: These attributes outline what this geocoding represents - a place, landmark, site, coordinate, etc.
    //-------------------
    /**
     * 
     * @return true if geocoding represents a named place
     */
    public boolean isPlace();

    /**
     * isCoordinate: if this object represents a coordinate
     * 
     * @return true if geocoding represents a coordinate
     */
    public boolean isCoordinate();

    /**
     * has Coordinate: if this named place object has a coordinate.
     * 
     * @return true if geocoding represents has a valid lat, lon
     */
    public boolean hasCoordinate();

    public boolean isCountry();

    public boolean isAdministrative();

    /**
     * Precision - radius in meters of possible error
     * @return precision error radius
     */
    public int getPrecision();

    /**
     * Precision - radius in meters of possible error
     * @param m meters of error
     */
    public void setPrecision(int m);

    //---------------------
    // entity metadata:
    //---------------------
    public String getCountryCode();

    public void setCountryCode(String cc);

    public void setCountry(Country c);

    public String getAdmin1();

    public String getAdmin2();

    public String getAdminName();

    public String getAdmin1Name();

    public String getAdmin2Name();

    public String getFeatureClass();

    public String getFeatureCode();

    public String getPlaceID();

    public String getPlaceName();

    public void setPlaceName(String n);

    /** State-level postal code, the corresponds usually to ADM1 
     * @return optional postal code
     */
    public String getAdmin1PostalCode();

    /** City-level postal code, that may be something like a zip. 
     * Thinking world-wide, not everyone calls these zipcodes, as in the US. 
     * @return optional postal code
     */
    public String getPlacePostalCode();

    /**
     * @return Method for determining geocoding
     */
    public String getMethod();

    public void setMethod(String m);

    /**
     * Confidence metric is a normalized 100-point scale.
     * Xponents conventions are simple, so value of confidence is an integer.
     * @return value on a 100 point scale.
     */
    public int getConfidence();

    /**
     * Set confidence, a value on a 100 point scale, 0-100.
     * Yes values above or below scale are allowed, however 
     * it may be difficult to compare such values.  The intent is to normalize
     * all confidence metrics to this relative scale for your application.
     * @param c confidence 
     */
    public void setConfidence(int c);
}