The UsState2010 Database provides the state (or equivalent) within the United States (e.g., California, New York, or Washington, D.C.) for a given location (latitude and longitude).

States are part of the USCensus Bureau's strict organizational hierarchichy in which the territory of the United States is recursively subdivided into states, counties, county subdivisions, census tracts, census block groups, and census blocks.

Using the UsState2010 Database is simple: you give latitude and longitude and the Database returns the state's name, and several other identifying codes and basic statistics. It also returns more than 200 key demographic variables from the 2010 US Census and the related 5-year American Community Survey, including detailed information on the age, sex, race, employment, educational attainment, marital status, and income of the residents, as well as information about households, property values, and mortgage status. For a complete listing of the data returned, please see the Returned Values Section below.

This Database is based on data from the United States Census Bureau. In addition to repackaging that data in an easy-to-use format for Web developers and Java and .NET programmers, AskGeo also adds a high-performance spatial index that allows for extremely low-latency queries. Please see the Performance Section below for details on how fast this Database is.

As with most of the Databases constructed from data from the US Census, the Database's map comes in a low-fidelity and a high-fidelity version. The low-fidelity versions are faster to build and query and require less memory but are less geographically accurate. The high-fidelity versions have a smaller maximum geographical error and properly deal with the boundaries that occur over water, such as with coastal states and states touching the Great Lakes.

Note that the fidelity only pertains to the geographic accuracy of the map, not to the values in the data returned. So in the low-fidelity version, when you're close to a boundary, it may give you the data for the neighboring region, but it'll give you the correct data for the region actually picked.

When you buy a license you get access to both versions, so you can use whichever one you prefer.

US States Map

The map below was generated from the low-fidelity version of the UsState2010 Database.

The map below was generated from the high-fidelity version of the UsState2010 Database.

The Low Fidelity map is based on the US Census cartographic boundary map and the High Fidelity map is based on the internationally accepted borders and divisions of interior lakes.

The High Fidelity map may look simpler when zoomed out since it follows the borders as opposed to the coastlines, but it is sampled with much higher accuracy in the details.

The colors for each state have been selected randomly to provide contrast, but consistently between the two versions to allow for easy comparison.

Please also note that for locations not inside any state the Database returns the nearest state up to 100 km away. This "snap-to" distance is fixed for the Web API but can be customized by users of the AskGeo Java and .NET Libraries.

Please note that the Web API is based on the low-fidelity version.

Database Statistics

The UsState2010 Database consists of 51 states (including Washington D.C.) with the following statistical characteristics:

PopulationArea
Minimum563,626 people61 square miles
First Quartile1,567,582 people30,820 square miles
Median4,339,367 people53,626 square miles
Third Quartile6,724,540 people81,751 square miles
Maximum37,253,956 people591,859 square miles

Map Accuracy

As noted in the sections above, most Databases based on US Census data come in both high-fidelity and low-fidelity versions.

The high-fidelity version is the most accurate map data available from the US Census Bureau. Though the Census Bureau does not specify an explicit scale, they do quote source materials with scales of 1:100,000 and 1:24,000, and an Accuracy Improvement Project that led to an average error of just 7.6 meters. Our inspection of the data also reveals a high level of consistency with Google Maps and Open Street Map.

The low-fidelity version has an explicit scale of 1:500,000. Furthermore, borders that pass over bodies of water are snapped to the shoreline, unlike in the high-fidelity version.

Returned Values

The UsState2010 Database returns a large number of parameters about the state in question. While all these parameters are returned with a single call to the Web API, for performance reasons the Java and .NET Libraries divide them into four separate groups.

The first group is common to all the Databases and pertains to the query point's relationship to the map region from which the returned values were drawn.

KeyDescriptionUnitsType
AskGeoId The internally-used AskGeo unique ID for the returned polygon n/aint
IsInside Whether or not the query point is inside the returned polygon n/aboolean
MinDistanceKm The distance from the query point to the nearest interior point of the returned polygon kilometersfloat

The second group differs between the low-fidelity and high-fidelity versions.

The low-fidelity version returns the following (please note that the Web API uses the low-fidelity version):

KeyDescriptionUnitsType
GeoId US census unique geographic ID n/aString
StateCode US state FIPS code n/aString
StateName US state name (for example, California, New York, Wisconsin) n/aString
Lsad US census LSAD (logical/statistical area description) n/aString
CensusAreaSqMi US census area (square miles) square milesfloat

The high-fidelity version returns the following:

KeyDescriptionUnitsType
RegionCode US census region code n/aString
DivisionCode US census division code n/aString
StateCode US state FIPS code n/aString
StateAnsiCode US state ANSI code n/aString
GeoId US census unique geographic ID n/aString
StatePostalCode US Postal Service state abbreviation (for example, CA, NY, WI) n/aString
StateName US state name (for example, California, New York, Wisconsin) n/aString
Lsad US census LSAD (logical/statistical area description) n/aString
FeatureClassCode US census MAF/TIGER feature class code n/aString
FunctionalStatus US census functional status code n/aString
LandAreaSqM US census land area (square meters) square metersfloat
WaterAreaSqM US census water area (square meters) square metersfloat
LatitudeDeg Latitude of interior point (degrees) degreesfloat
LongitudeDeg Longitude of interior point (degrees) degreesfloat

The next two groups are the same in both the high-fidelity and low-fidelity versions. First, we offer selected demographic census data from the official 2010 Census for the state:

KeyDescriptionUnitsType
CensusGeoId Unique geographic identifier n/aString
CensusGeoLevel Geographic level code n/aString
CensusEsriId ESRI entity code n/aString
CensusGeoCode US Census entity code n/aString
CensusAreaName Entity name n/aString
CensusStateAbbreviation State abbreviation n/aString
CensusTotalPopulation Total Population peoplefloat
CensusTotalPopulationIn2000 Total Population in 2000 peoplefloat
CensusTotalPopulationChange2000To2010 Change in Population 2000-2010 peoplefloat
CensusTotalPopulationPercentChange2000To2010 Percent Change in Population 2000-2010 percentfloat
CensusSexMale Sex: Males peoplefloat
CensusSexPercentMale Sex: Percent Males percentfloat
CensusSexFemale Sex: Females peoplefloat
CensusSexPercentFemale Sex: Percent Females percentfloat
CensusPeoplePerSqMi Population Density people per square milefloat
CensusAge0To4 Age: Under 5 Years peoplefloat
CensusAgePercent0To4 Age: Percent Under 5 Years percentfloat
CensusAge5To9 Age: Age 5 to 9 Years peoplefloat
CensusAgePercent5To9 Age: Percent Age 5 to 9 Years percentfloat
CensusAge10To14 Age: 10 to 14 Years peoplefloat
CensusAgePercent10To14 Age: Percent 10 to 14 Years percentfloat
CensusAge15To17 Age: 15 to 17 Years peoplefloat
CensusAgePercent15To17 Age: Percent 15 to 17 Years percentfloat
CensusAge18To19 Age: 18 to 19 Years peoplefloat
CensusAgePercent18To19 Age: Percent 18 to 19 Years percentfloat
CensusAge20To24 Age: 20 to 24 Years peoplefloat
CensusAgePercent20To24 Age: Percent 20 to 24 Years percentfloat
CensusAge25To34 Age: 25 to 34 Years peoplefloat
CensusAgePercent25To34 Age: Percent 25 to 34 Years percentfloat
CensusAge35To44 Age: 35 to 44 Years peoplefloat
CensusAgePercent35To44 Age: Percent 35 to 44 Years percentfloat
CensusAge45To54 Age: 45 to 54 Years peoplefloat
CensusAgePercent45To54 Age: Percent 45 to 54 Years percentfloat
CensusAge55To59 Age: 55 to 59 Years peoplefloat
CensusAgePercent55To59 Age: Percent 55 to 59 Years percentfloat
CensusAge60To64 Age: 60 to 64 Years peoplefloat
CensusAgePercent60To64 Age: Percent 60 to 64 Years percentfloat
CensusAge65To74 Age: 65 to 74 Years peoplefloat
CensusAgePercent65To74 Age: Percent 65 to 74 Years percentfloat
CensusAge75To84 Age: 75 to 84 Years peoplefloat
CensusAgePercent75To84 Age: Percent 75 to 84 Years percentfloat
CensusAgeOver85 Age: 85 Years and Over peoplefloat
CensusAgePercentOver85 Age: Percent 85 Years and Over percentfloat
CensusAgeMedianAge Age: Median Age yearsfloat
CensusAgeUnder18 Age: 0 to 17 Years peoplefloat
CensusAgePercentUnder18 Age: Percent 0 to 17 percentfloat
CensusAge18To24 Age: 18 to 24 Years peoplefloat
CensusAgePercent18To24 Age: Percent 18 to 24 Years percentfloat
CensusAge25To44 Age: 25 to 44 Years peoplefloat
CensusAgePercent25To44 Age: Percent 25 to 44 Years percentfloat
CensusAge45To64 Age: 45 to 64 Years peoplefloat
CensusAgePercent45To64 Age: Percent 45 to 64 Years percentfloat
CensusAgeOver62 Age: 62 Years and Over peoplefloat
CensusAgePercentOver62 Age: Percent 62 Years and Over percentfloat
CensusAgeOver65 Age: 65 Years and Over peoplefloat
CensusAgePercentOver65 Age: Percent 65 Years and Over percentfloat
CensusAgeOver18 Age: 18 Years and Over peoplefloat
CensusAgePercentOver18 Age: Percent 18 Years and Over percentfloat
CensusAgeOver18Male Age: Males 18 Year and Over peoplefloat
CensusAgePercentOver18Male Age: Percent Males 18 Years and Over percentfloat
CensusAgeOver18Female Age: Females 18 Year and Over peoplefloat
CensusAgePercentOver18Female Age: Percent Females 18 Years and Over percentfloat
CensusAgeOver21 Age: 21 Years and Over peoplefloat
CensusAgePercentOver21 Age: Percent 21 and Over percentfloat
CensusAge15To19 Age: 15 to 19 Years peoplefloat
CensusAgePercent15To19 Age: Percent 15 to 19 Years percentfloat
CensusAgeOver65Male Age: Males 65 and Over peoplefloat
CensusAgePercentOver65Male Age: Percent Males 65 and Over percentfloat
CensusAgeOver65Female Age: Females 65 and Over peoplefloat
CensusAgePercentOver65Female Age: Percent Females 65 and Over percentfloat
CensusRaceOneRaceOnly Race: One Race peoplefloat
CensusRacePercentOneRaceOnly Race: Percent One Race percentfloat
CensusRaceWhiteOnly Race: White peoplefloat
CensusRacePercentWhiteOnly Race: Percent White percentfloat
CensusRaceBlackOnly Race: Black or African American peoplefloat
CensusRacePercentBlackOnly Race: Percent Black or African American percentfloat
CensusRaceIndian Race: American Indian and Alaska Native peoplefloat
CensusRacePercentIndian Race: Percent American Indian and Alaska Native percentfloat
CensusRaceAsianOnly Race: Asian peoplefloat
CensusRacePercentAsianOnly Race: Percent Asian percentfloat
CensusRaceHawaiianPIOnly Race: Native Hawaiian and Other Pacific Islander peoplefloat
CensusRacePercentHawaiianPIOnly Race: Percent Native Hawaiian and Other Pacific Islander percentfloat
CensusRaceOtherOnly Race: Some Other Race peoplefloat
CensusRacePercentOtherOnly Race: Percent Some Other Race percentfloat
CensusRaceMultiRace Race: Multi Race: Persons reporting more than one race peoplefloat
CensusRacePercentMultiRace Race: Percent Multi Race: Persons reporting more than one race percentfloat
CensusHispanicTotalPopulation Hispanic: Hispanic or Latino (of any race) peoplefloat
CensusHispanicPercentHispanic Hispanic: Percent Hispanic or Latino (of any race) percentfloat
CensusHispanicMexican Hispanic: Mexican peoplefloat
CensusHispanicPercentMexican Hispanic: Percent Mexican percentfloat
CensusHispanicPuertoRican Hispanic: Puerto Rican peoplefloat
CensusHispanicPercentPuertoRican Hispanic: Percent Puerto Rican percentfloat
CensusHispanicCuban Hispanic: Cuban peoplefloat
CensusHispanicPercentCuban Hispanic: Percent Cuban percentfloat
CensusHispanicOtherHispanic Hispanic: Other Hispanic or Latino peoplefloat
CensusHispanicPercentOtherHispanic Hispanic: Percent Other Hispanic or Latino percentfloat
CensusHispanicNonHispanic Hispanic: Not Hispanic or Latino peoplefloat
CensusHispanicPercentNonHispanic Hispanic: Percent Not Hispanic or Latino percentfloat
CensusHispanicWhiteNonHispanic Hispanic: White Alone Not Hispanic peoplefloat
CensusHispanicPercentWhiteNonHispanic Hispanic: Percent White Alone Not Hispanic percentfloat
CensusHouseholdsTotal Households: Total Households householdsfloat
CensusHouseholdsTotalFamilies Households: Family Households (Families) householdsfloat
CensusHouseholdsPercentFamilies Households: Percent Family Households (Families) percentfloat
CensusHouseholdsFamilyKidsUnder18 Households: With Own Children Under 18 Years householdsfloat
CensusHouseholdsPercentFamilyKidsUnder18 Households: Percent With Own Children Under 18 Years percentfloat
CensusHouseholdsMarriedCouple Households: Married Couple Family householdsfloat
CensusHouseholdsPercentMarriedCouple Households: Percent Married Couple Family percentfloat
CensusHouseholdsMarriedCoupleKidsUnder18 Households: With Own Children Under 18 Years householdsfloat
CensusHouseholdsPercentMarriedCoupleKidsUnder18 Households: Percent With Own Children Under 18 Years percentfloat
CensusHouseholdsFemaleHouseholder Households: Female householder No Husband Present householdsfloat
CensusHouseholdsPercentFemaleHouseholder Households: Percent Female householder No Husband Present percentfloat
CensusHouseholdsSingleMoms Households: With Own Children Under 18 Years householdsfloat
CensusHouseholdsPercentSingleMoms Households: Percent With Own Children Under 18 Years percentfloat
CensusHouseholdsNonFamily Households: Non Family Households householdsfloat
CensusHouseholdsPercentNonFamily Households: Percent Non Family Households percentfloat
CensusHouseholdsUnmarriedPartner Households: Unmarried Partner Households householdsfloat
CensusHouseholdsPercentUnmarriedPartner Households: Percent Unmarried Partner Households percentfloat
CensusHouseholdsSameSexPartner Households: Same-Sex Unmarried Partner Households householdsfloat
CensusHouseholdsPercentSameSexPartner Households: Percent Same-Sex Unmarried Partner Households percentfloat
CensusHouseholdsLivingAlone Households: Householder Living Alone householdsfloat
CensusHouseholdsPercentLivingAlone Households: Percent Householder Living Alone percentfloat
CensusHouseholdsHouseholderOver65 Households: Householder 65 Years and Over householdsfloat
CensusHouseholdsPercentHouseholderOver65 Households: Percent Householder 65 Years and Over percentfloat
CensusHouseholdsHouseholdsWithUnder18 Households: Households With Individuals Under 18 Years householdsfloat
CensusHouseholdsPercentHouseholdsWithUnder18 Households: Percent Households With Individuals Under 18 Years percentfloat
CensusHouseholdsWithOver65 Households: Households With Individuals 65 Years and Over householdsfloat
CensusHouseholdsPercentWithOver65 Households: Percent Households With Individuals 65 Years and Over percentfloat
CensusHouseholdsAverageHouseholdSize Households: Average Household Size peoplefloat
CensusHouseholdsAverageFamilySize Households: Average Family Size peoplefloat

Second, we offer additional economic and housing data from the 5-year American Community Survey (2006-2010 inclusive) from the US Census Bureau:

KeyDescriptionUnitsType
AcsGeoId Unique geographic identifier n/aString
AcsComponent Component code n/aString
AcsTotalPopulation Total Population peoplefloat
AcsRaceTotalPopulation Race: Total population peoplefloat
AcsRaceWhiteOnly Race: White alone peoplefloat
AcsRaceBlackOnly Race: Black or African American alone peoplefloat
AcsRaceAmericanIndianOnly Race: American Indian and Alaska Native alone peoplefloat
AcsRaceAsianOnly Race: Asian alone peoplefloat
AcsRaceHawaiianPIOnly Race: Native Hawaiian and Other Pacific Islander alone peoplefloat
AcsRaceOtherOnly Race: Some other race alone peoplefloat
AcsRaceMulti Race: Two or more races peoplefloat
AcsRaceMultiWithOther Race: Two or more races including some other race peoplefloat
AcsRaceMultiMore Race: Three or more races, and two races excluding some other race peoplefloat
AcsHispanicTotalPolulation Hispanic: Total population peoplefloat
AcsHispanicAllNonHispanic Hispanic: Non-Hispanics of all races peoplefloat
AcsHispanicWhiteNonHispanic Hispanic: White non-Hispanics peoplefloat
AcsHispanicAllHispanic Hispanic: Hispanics of all races peoplefloat
AcsHispanicWhiteHispanic Hispanic: White Hispanics peoplefloat
AcsAgeMedianAge Median age yearsfloat
AcsAgeMaleMedianAge Male median age yearsfloat
AcsAgeFemaleMedianAge Female median age yearsfloat
AcsSexTotalPolulation Sex: Total population peoplefloat
AcsSexMales Sex: Males peoplefloat
AcsSexFemales Sex: Females peoplefloat
AcsAgeUnder18 Population under 18 years old peoplefloat
AcsHouseholdIncomeTotalPopulation Household income: Total population peoplefloat
AcsHouseholdIncomeBelow10k Household income: Less than $10,000 peoplefloat
AcsHouseholdIncome10To15k Household income: $10,000 to $14,999 peoplefloat
AcsHouseholdIncome15To20k Household income: $15,000 to $19,999 peoplefloat
AcsHouseholdIncome20To25k Household income: $20,000 to $24,999 peoplefloat
AcsHouseholdIncome25To30k Household income: $25,000 to $29,999 peoplefloat
AcsHouseholdIncome30To35k Household income: $30,000 to $34,999 peoplefloat
AcsHouseholdIncome35To40k Household income: $35,000 to $39,999 peoplefloat
AcsHouseholdIncome40To45k Household income: $40,000 to $44,999 peoplefloat
AcsHouseholdIncome45To50k Household income: $45,000 to $49,999 peoplefloat
AcsHouseholdIncome50To60k Household income: $50,000 to $59,999 peoplefloat
AcsHouseholdIncome60To75k Household income: $60,000 to $74,999 peoplefloat
AcsHouseholdIncome75To100k Household income: $75,000 to $99,999 peoplefloat
AcsHouseholdIncome100To125k Household income: $100,000 to $124,999 peoplefloat
AcsHouseholdIncome125To150k Household income: $125,000 to $149,999 peoplefloat
AcsHouseholdIncome150To200k Household income: $150,000 to $199,999 peoplefloat
AcsHouseholdIncome200kPlus Household income: $200,000 or more peoplefloat
AcsHouseholdIncomeMedian Median household income dollarsfloat
AcsIncomePerCapita Per capita income dollarsfloat
AcsHousingUnitsTotalNumber Housing Units: Total housing unitsfloat
AcsHousingUnitsOccupancyTotalNumber Housing Units: Occupancy Status: Total housing unitsfloat
AcsHousingUnitsOccupied Housing Units: Occupancy Status: Occupied housing unitsfloat
AcsHousingUnitsVacant Housing Units: Occupancy Status: Vacant housing unitsfloat
AcsGrossRentMedian Median gross rent dollarsfloat
AcsHouseValueOwnerOccupied25thPercentile Owner-Occupied Housing Units: Value: 25th percentile dollarsfloat
AcsHouseValueOwnerOccupiedMedian Owner-Occupied Housing Units: Value: Median dollarsfloat
AcsHouseValueOwnerOccupied75thPercentile Owner-Occupied Housing Units: Value: 75th percentile dollarsfloat
AcsMortgageStatusTotalNumber Owner-Occupied Housing Units: Mortgage Status: Total housing unitsfloat
AcsMortgageStatusWithMortgage Owner-Occupied Housing Units: Mortgage Status: With mortgage or similar housing unitsfloat
AcsMortgageStatusWithoutMortgage Owner-Occupied Housing Units: Mortgage Status: Without mortgage or similar housing unitsfloat
AcsGrossRentAsPctHousholdIncome Median gross rent as a percentage of household income percentfloat
AcsRoomsNumberMedian Median number of rooms roomsfloat
AcsUnitsInStructureTotalUnits Units in Structure: Total units housing unitsfloat
AcsUnitsInStructure1Detached Units in Structure: 1, detached housing unitsfloat
AcsUnitsInStructure1Attached Units in Structure: 1, attached housing unitsfloat
AcsUnitsInStructure2 Units in Structure: 2 housing unitsfloat
AcsUnitsInStructure3To4 Units in Structure: 3 or 4 housing unitsfloat
AcsUnitsInStructure5To9 Units in Structure: 5 to 9 housing unitsfloat
AcsUnitsInStructure10To19 Units in Structure: 10 to 19 housing unitsfloat
AcsUnitsInStructure20To49 Units in Structure: 20 to 49 housing unitsfloat
AcsUnitsInStructure50Plus Units in Structure: 50 or more housing unitsfloat
AcsUnitsInStructureMobileHome Units in Structure: Mobile home housing unitsfloat
AcsUnitsInStructureBoatRvVan Units in Structure: Boat, RV, van, etc. housing unitsfloat
AcsHouseholdIncome20thPercentile Household income: 20th percentile dollarsfloat
AcsHouseholdIncome40thPercentile Household income: 40th percentile dollarsfloat
AcsHouseholdIncome60thPercentile Household income: 60th percentile dollarsfloat
AcsHouseholdIncome80thPercentile Household income: 80th percentile dollarsfloat
AcsHouseholdIncome95thPercentile Household income: 95th percentile dollarsfloat
AcsHousingCostsMonthlyMedian Median monthly housing costs dollarsfloat
AcsEducationTotalPopulation Educational Attainment (25 and older): Total population peoplefloat
AcsEducationMale Educational Attainment (25 and older): Male: Total population peoplefloat
AcsEducationMaleHighSchool Educational Attainment (25 and older): Male: High school graduate, GED, or alternative peoplefloat
AcsEducationMaleLittleCollege Educational Attainment (25 and older): Male: Some college, less than 1 year peoplefloat
AcsEducationMaleSomeCollege Educational Attainment (25 and older): Male: Some college, 1 or more years, no degree peoplefloat
AcsEducationMaleAssociatesDegree Educational Attainment (25 and older): Male: Associate's degree peoplefloat
AcsEducationMaleBachelorsDegree Educational Attainment (25 and older): Male: Bachelor's degree peoplefloat
AcsEducationMaleMastersDegree Educational Attainment (25 and older): Male: Master's degree peoplefloat
AcsEducationMaleProfessionalSchoolDegree Educational Attainment (25 and older): Male: Professional school degree peoplefloat
AcsEducationMaleDoctorateDegree Educational Attainment (25 and older): Male: Doctorate degree peoplefloat
AcsEducationFemale Educational Attainment (25 and older): Female: Total population peoplefloat
AcsEducationFemaleHighSchool Educational Attainment (25 and older): Female: High school graduate, GED, or alternative peoplefloat
AcsEducationFemaleLittleCollege Educational Attainment (25 and older): Female: Some college, less than 1 year peoplefloat
AcsEducationFemaleSomeCollege Educational Attainment (25 and older): Female: Some college, 1 or more years, no degree peoplefloat
AcsEducationFemaleAssociatesDegree Educational Attainment (25 and older): Female: Associate's degree peoplefloat
AcsEducationFemaleBachelorsDegree Educational Attainment (25 and older): Female: Bachelor's degree peoplefloat
AcsEducationFemaleMastersDegree Educational Attainment (25 and older): Female: Master's degree peoplefloat
AcsEducationFemaleProfessionalSchoolDegree Educational Attainment (25 and older): Female: Professional school degree peoplefloat
AcsEducationFemaleDoctorateDegree Educational Attainment (25 and older): Female: Doctorate degree peoplefloat
AcsMaritalStatusWomen15To50TotalPopulation Marital Status by Age for Women 15 To 50 Years: Total population peoplefloat
AcsMaritalStatusWomen15To50Married Marital Status by Age for Women 15 To 50 Years: Now married (including spouse absent) peoplefloat
AcsMaritalStatusWomen15To50Unmarried Marital Status by Age for Women 15 To 50 Years: Unmarried (never married, widowed, and divorced) peoplefloat
AcsLanguageSpokenAtHomeTotalPopulation Language Spoken at Home (5 and older): Total population peoplefloat
AcsLanguageSpokenAtHomeEnglishOnly Language Spoken at Home (5 and older): Speak only English peoplefloat
AcsLanguageSpokenAtHomeSpanish Language Spoken at Home (5 and older): Spanish or Spanish Creole peoplefloat
AcsWorkTransportationTotalPopulation Means of Transportation to Work: Total population peoplefloat
AcsWorkTransportationCarTruckVan Means of Transportation to Work: Car, truck, or van peoplefloat
AcsWorkTransportationPublicTransit Means of Transportation to Work: Public transportation (excluding taxicab) peoplefloat
AcsWorkTransportationWorkAtHome Means of Transportation to Work: Worked at home peoplefloat
AcsGiniIndex Gini Index of income inequality gini indexfloat
AcsMedianEarningsByOccupationAllOccupations Median earnings by occupation (civilian, 16 and older): Total population dollarsfloat
AcsMedianEarningsByOccupationManagement Median earnings by occupation (civilian, 16 and older): Management, business, science, and arts occupations dollarsfloat
AcsMedianEarningsByOccupationService Median earnings by occupation (civilian, 16 and older): Service occupations dollarsfloat
AcsMedianEarningsByOccupationSales Median earnings by occupation (civilian, 16 and older): Sales and office occupations dollarsfloat
AcsMedianEarningsByOccupationConstruction Median earnings by occupation (civilian, 16 and older): Natural resources, construction, and maintenance occupations dollarsfloat
AcsMedianEarningsByOccupationProduction Median earnings by occupation (civilian, 16 and older): Production, transportation, and material moving occupations dollarsfloat
AcsGeoLevel Geographic level code n/aString
AcsStateCode US census state code n/aString
AcsCountyCode US census county code n/aString
AcsTractCode US census tract code n/aString
AcsBlockGroupCode US census block group code n/aString

Java Library

All AskGeo Java Libraries are compatible with Java 6, have no external dependencies, and are thread safe. Each Database comes with an associated Data File that must provided at constructor time to populate the internal data structures.

The libraries come in both double and single (float) precision versions, with the former consuming just under twice the resident memory of the latter. For reference, the single precision version is accurate to about 2.4 meters, which is more than sufficient for most applications.

As noted above, the UsState2010 Java Libary comes in two different geographic fidelity levels. The high fidelity version is larger on disk and in memory, but offers greater geographic precision.

If you are interested in purchasing this Library or gaining access to the Web API, please see the:

Price List

Java Documentation

There are only four classes that you need to be aware of to use the AskGeo UsState2010 Java Library, and only the first two are essential:

class UsStateMap

Contains map data and allows queries on the Database.

class UsStateResult

Embodies the result of a query on a UsStateMap instance.

enum CensusField

Enumeration of the result fields taken from the 2010 US Census.

enum AcsField

Enumeration of the result fields taken from the 2006-2010 US Census Bureau's American Community Survey.

They are described in the sections that follow.

The method signatures listed in this section are for the single precision (float) version of the library. For the double precision version, just replace float with double.

Please note that the documentation below is intended to provide you with an easy-to-understand presentation of the essentials of how to use the AskGeo UsState2010 Java Library.

For full documentation of the classes included, please see the:

Full Java Docs

UsStateMap

The UsStateMap class stores the map data and exposes a query method to find the state and related metadata at a given latitude and longitude. Because each UsStateMap instance is quite large, we recommend instantiating a single static instance in your project. The methods that you will need to use are as follows.

class UsStateMap {
static UsStateMap create(InputStream dataFileStream)
Factory method for building a UsStateMap instance.
  • InputStream dataFileStream: Input Stream of the Data File to be read to create this map
UsStateResult findResult(float latDeg, float lonDeg)
Query method returns a UsStateResult instance for a given latitude and longitude. Returns null if no result is found.
  • float latDeg: Latitude of the query point (degrees)
  • float lonDeg: Longitude of the query point (degrees)
// Additional methods exist in this class; for complete documentation, please see the Full Java Docs
}

UsStateResult

The UsStateResult class embodies the result of a query on a UsStateMap instance. All of the results listed in the Returned Values Section may be accessed using an accessor whose method name consists of "get" followed by the Key parameter from the Returned Values tables. Those tables also specify the type of the returned value. For example, here are several important accessors:

class UsStateResult {
String getStateName()
Returns the name of the state.
float GetCensusTotalPopulation()
Returns the total population in the state.
float GetCensusAgeMedianAge()
Returns the median age of the residents of the state.
float GetAcsHouseholdIncomeMedian()
Returns the median household income of the residents of the state.
// Additional methods exist in this class; for complete documentation, please see the Full Java Docs
}
Note: these are just a few of literally hundreds of accessors listed above in the Returned Values Section.

CensusField and AcsField

The CensusField and AcsField enums lists the fields taken from the 2010 US Census and 2006-2010 American Community Survey that are reported for each state. These may be used with the UsStateResult to access these data if, for whatever reason, the more traditional accessors are not suitable to the application at hand. For example, some applications might result in having a list of desired fields, which could be represented as a list of CensusField or AcsField members, and accessed in a for loop.

The following methods on the UsStateResult class work with these enums:

class UsStateResult {
String getAcsField(AcsField field)
Returns the String representation of the given 2006-2010 American Community Survey field, or null or an empty String if that field is missing.
  • AcsField field: The field to look up
float getAcsFieldAsFloat(AcsField field)
Returns the float representation of the given 2006-2010 American Community Survey field, or Float.NaN if that field is missing.
  • AcsField field: The field to look up
String getCensusField(CensusField field)
Returns the String representation of the given 2010 US Census field, or null or an empty String if that field is missing.
  • CensusField field: The field to look up
float getCensusFieldAsFloat(CensusField field)
Returns the float representation of the given 2010 US Census field, or Float.NaN if that field is missing.
  • CensusField field: The field to look up
// Additional methods exist in this class; for complete documentation, please see the Full Java Docs
}

Please note that if you are just trying to access a couple of fields that are known at compile time, it is probably much easier to use the direct accessors documented here.

Java Example

The following is a complete example program demonstrating the use of the AskGeo UsState2010 Java Library.

import com.askgeo.flt.base.AcsField;
import com.askgeo.flt.us.census2010.low.UsStateMap;
import com.askgeo.flt.us.census2010.low.UsStateResult;

import java.io.FileInputStream;

public class UsCensusExample {
    static float[][] examplePoints = {{37f, -122f}, {42f, -89f}};
    static String license = "INSERT YOUR LICENSE STRING HERE";
    static String dataFilePath = "askgeo-us-state-2010-low-1.1.0.dat";

    public static void main(String[] args) {
        try {
            UsStateMap map = UsStateMap.create(new FileInputStream(dataFilePath));
            map.authorize(license);
            for (float[] point : examplePoints) {
                UsStateResult result = map.findResult(point[0], point[1]);
                String name = result.getStateName();
                float population = result.getCensusTotalPopulation();
                float medianAge = result.getCensusAgeMedianAge();
                float medianIncome = result.getAcsFieldAsFloat(AcsField.AcsHouseholdIncomeMedian);
                System.out.println(" Latitude: " + point[0] +
                        ", Longitude: " + point[1] +
                        ", Name: " + name +
                        ", Population: " + population +
                        ", Median Age: " + medianAge +
                        ", Median Income: " + medianIncome);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }

    }
}

Java Library Performance and Memory Consumption

AskGeo was designed from the ground up to be high performance. Our custom spatial index delivers blazing-fast response times. Furthermore, we've designed the AskGeo Java Libraries to be thread safe and to not utilize synchronized methods or statements in the performance-critical query code. This means that computers with multiple processors or cores can take full advantage of those cores to deliver even faster performance.

We tested the performance of the Library using a single thread on a computer with an Intel Core i7 3.33 GHz running 64-bit Windows 7. For each version of the library, we tested:

Construction Time

The time it took to construct an instance of the UsState2010 Database object.

Per-Query Time

The average response time for a single query. This was measured by running 100,000 queries, randomly distributed over the full extent of the map.

Memory

Resident memory of a UsState2010 Database instance, as estimated by measuring the JVM's used memory after running the GC when running a simple test application containing only the map. This will lead to a slight over-estimate of the resident memory because it will include the overhead of the test application.

Data File Size

The file size of the Data File associated with this Database.

FidelityPrecisionConstruction TimePer-Query TimeMemoryData File Size
LowSingle 0.32 seconds 3.63e-05 seconds 2.3 MB0.8 MB
LowDouble 0.20 seconds 3.68e-05 seconds 3.0 MB0.8 MB
HighSingle 0.88 seconds 2.16e-04 seconds 8.2 MB5.5 MB
HighDouble 0.80 seconds 2.21e-04 seconds 14.8 MB5.5 MB

.NET Library

All AskGeo .NET Libraries are compatible with .NET 4 and are thread safe. Each Database comes with an associated Data File that must provided at constructor time to populate the internal data structures. Except for a few small changes to be more consistent with .NET style and coding conventions, the AskGeo .NET Libraries are a direct port of the AskGeo Java Libraries.

Where relevant both double and single (float) precision versions of the various classes are provided, with the former consuming just under twice the resident memory of the latter. For reference, the single precision version is accurate to about 2.4 meters, which is more than sufficient for most applications.

As noted above, the UsState2010 .NET Libary comes in two different geographic fidelity levels. The high fidelity version is larger on disk and in memory, but offers greater geographic precision.

If you are interested in purchasing this Library or gaining access to the Web API, please see the:

Price List

.NET Documentation

There are only four classes that you need to be aware of to use the AskGeo UsState2010 .NET Library, and only the first two are essential:

class UsStateMap

Contains map data and allows queries on the Database.

class UsStateResult

Embodies the result of a query on a UsStateMap instance.

class CensusField

Enumerates (with static public members) the result fields taken from the 2010 US Census.

class AcsField

Enumerates (with static public members) the result fields taken from the 2006-2010 US Census Bureau's American Community Survey.

They are described in the sections that follow.

The method signatures listed in this section are for the single precision (float) version of the library. For the double precision version, just replace float with double.

Please note that the documentation below is intended to provide you with an easy-to-understand presentation of the essentials of how to use the AskGeo UsState2010 .NET Library.

For full documentation of the classes included, please see the:

Full .NET Docs

UsStateMap

The UsStateMap class stores the map data and exposes a query method to find the state and related metadata at a given latitude and longitude. Because each UsStateMap instance is quite large, we recommend instantiating a single static instance in your project. The methods that you will need to use are as follows.

class UsStateMap {
static UsStateMap Create(Stream dataFileStream)
Factory method for building a UsStateMap instance.
  • Stream dataFileStream: Input Stream of the Data File to be read to create this map
UsStateResult FindResult(float latDeg, float lonDeg)
Query method returns a UsStateResult instance for a given latitude and longitude. Returns null if no result is found.
  • float latDeg: Latitude of the query point (degrees)
  • float lonDeg: Longitude of the query point (degrees)
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}

UsStateResult

The UsStateResult class embodies the result of a query on a UsStateMap instance. All of the results listed in the Returned Values Section may be accessed using an accessor whose method name consists of "Get" followed by the Key parameter from the Returned Values tables. Those tables also specify the type of the returned value. For example, here are several important accessors:

class UsStateResult {
String GetStateName()
Returns the name of the state.
float GetCensusTotalPopulation()
Returns the total population in the state.
float GetCensusAgeMedianAge()
Returns the median age of the residents of the state.
float GetAcsHouseholdIncomeMedian()
Returns the median household income of the residents of the state.
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}
Note: these are just a few of literally hundreds of accessors listed above in the Returned Values Section.

CensusField and AcsField

The CensusField and AcsField classes lists (as static public members) the fields taken from the 2010 US Census and 2006-2010 American Community Survey that are reported for each state. These may be used with the UsStateResult to access these data if, for whatever reason, the more traditional accessors are not suitable to the application at hand. For example, some applications might result in having a list of desired fields, which could be represented as a list of CensusField or AcsField members, and accessed in a for loop.

The following methods on the UsStateResult class work with the static public members of these classes:

class UsStateResult {
String GetAcsField(AcsField field)
Returns the String representation of the given 2006-2010 American Community Survey field, or null or an empty String if that field is missing.
  • AcsField field: The field to look up
float GetAcsFieldAsFloat(AcsField field)
Returns the float representation of the given 2006-2010 American Community Survey field, or float.NaN if that field is missing.
  • AcsField field: The field to look up
String GetCensusField(CensusField field)
Returns the String representation of the given 2010 US Census field, or null or an empty String if that field is missing.
  • CensusField field: The field to look up
float GetCensusFieldAsFloat(CensusField field)
Returns the float representation of the given 2010 US Census field, or float.NaN if that field is missing.
  • CensusField field: The field to look up
// Additional methods exist in this class; for complete documentation, please see the Full .NET Docs
}

Please note that if you are just trying to access a couple of fields that are known at compile time, it is probably much easier to use the direct accessors documented here.

.NET Example

The following is a complete example program demonstrating the use of the AskGeo UsState2010 .NET Library.

using System;
using System.IO;
using AskGeo.Flt;
using AskGeo.Base;

class UsCensus {
    static void Main(string[] args) {
        float[,] examplePoints = { { 37f, -122f }, { 42f, -89f } };
        String license = "INSERT YOUR LICENSE STRING HERE";
        String dataFilePath = @"askgeo-us-state-2010-low-1.1.0.dat";

        UsStateLowMap map = UsStateLowMap.Create(new FileStream(dataFilePath, FileMode.Open));
        map.Authorize(license);

        for (int i = 0; i < examplePoints.GetLength(0); i++) {
            UsStateLowResult result = map.FindResult(examplePoints[i, 0], examplePoints[i, 1]);
            String name = result.GetStateName();
            float population = result.GetCensusTotalPopulation();
            float medianAge = result.GetCensusAgeMedianAge();
            float medianIncome = result.GetAcsFieldAsFloat(AcsField.AcsHouseholdIncomeMedian);
            Console.WriteLine(" Latitude: " + examplePoints[i, 0] +
                    ", Longitude: " + examplePoints[i, 1] +
                    ", Name: " + name +
                    ", Population: " + population +
                    ", Median Age: " + medianAge +
                    ", Median Income: " + medianIncome);

        }
    }
}

.NET Library Performance and Memory Consumption

AskGeo was designed from the ground up to be high performance. Our custom spatial index delivers blazing-fast response times. Furthermore, we've designed the AskGeo .NET Libraries to be thread safe and to not utilize synchronized methods or statements in the performance-critical query code. This means that computers with multiple processors or cores can take full advantage of those cores to deliver even faster performance.

The AskGeo Libraries were originally designed and written in Java and ported to .NET. Consequently, detailed performance and memory consumption information is available for the Java Libraries but not for the .NET Libraries. We have run spot checks on a few of our test cases and found that the .NET Libraries have essentially the same performance characteristics as the Java Libraries. This is unsurprising given the similarities between the languages and the virtual machines on which they run. See the Java Performance Section for detailed information on construction time, per-query time, and memory consumption.