Location Normalization

Overview

The Location Normalization method takes semi-structured location data via the place parameter, provided as a string, and returns structured location data in either JSON or XML format.

A likelihood value is also returned, indicating how confident we are that the structured response is accurate. To determine likelihood, we first validate the existence of the country, state and city. We then verify if the state in question is actually a child of the given country, and if a given city is a child of the state. If we cannot identify a state or city, this value will not effect the likelihood.

All location data is sourced from the the GeoNames geographical database, which covers all countries and contains over eight million place names.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/address/locationNormalizer.json?place=denver'

XML

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/address/locationNormalizer.xml?place=denver'

Parameters

place

The place parameter allows you to pass a semi-structured location string which can include continent, country, state, city, or county. County names must always be followed by the word "County" in your input string (ie. Collier County, Denver County, etc).

includeZeroPopulation (optional)

Appending includeZeroPopulation=true, will display 0 population census locations.

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/address/locationNormalizer.json?place=denver&includeZeroPopulation=true'

casing (optional)]

  • uppercase (DENVER, COLORADO)
  • lowercase (denver, colorado)
  • titlecase (Denver, Colorado)

Examples

The table below contains example API queries and responses. Values in the "place" column represent the API query input. The "status" column contains the HTTP status code, the remaining columns contain the API response data for the query. Normalized location data will always be returned in the "City, State, Country" format where applicable.

place Status City Zip Code County State Country Normalized Location Likelihood
denver 200 Denver Denver 1.0
denver, co 200 Denver Colorado Denver, Colorado 1.0
denver, co 80202 200 Denver 80202 Colorado Denver, Colorado 1.0
united states 200 United States United States 1.0
USA 200 United States United States 1.0
denver, colorado us 200 Denver Colorado United States Denver, Colorado, United States 1.0
denver county, colorado 200 Denver Colorado Colorado 1.0
Denver, Colorado, 80204, Denver County, USA, North America 200 Denver Denver Colorado United States Denver, Colorado, United States 1.0
adfasdfasd, colorado 200 Colorado Colorado 1.0
naples, colorado 200 Naples Colorado Naples, Colorado 0.5
asdfadsf 422

Responses

The API responds with JSON or XML.

JSON

{
  "status": 200,
  "city": "Denver",
  "state": {
    "name": "Colorado",
    "code": "CO"
  },
  "county": "Denver",
  "country": {
    "name": "United States",
    "code": "US"
  },
  "continent": "North America",
  "likelihood": "1.0",
  "normalizedLocation": "Denver, Colorado, United States"
}

XML

<?xml version="1.0" encoding="UTF-8" ?>
<location>
  <status>200</status>
  <city>Denver</city>
  <state>
    <name>Colorado</name>
    <code>CO</code>
  </state>
  <county>Denver</county>
  <country>
    <name>United States</name>
    <code>US</code>
  </country>
  <continent>North America</continent>
  <likelihood>1.0</likelihood>
  <normalizedLocation>Denver, Colorado, United States</normalizedLocation>
</location>

Location Enrichment

Overview

The Location Enrichment method takes semi-structured location data via the place parameter, provided as a string, and returns a collection of locations represented by the query. Each location returned includes city name, county, state, country, continent, population size, and a normalized location string. If more than one location is found for a given query, a collection of locations will be returned, sorted in descending order by the population size.

Requests

JSON

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/address/locationEnrichment.json?place=denver'

XML

curl -H"X-FullContact-APIKey:$your_key" 'https://api.fullcontact.com/v2/address/locationEnrichment.xml?place=denver'

Parameters

place

The place parameter allows you to pass a semi-structured location string which can include continent, country, state, city, or county.

includeZeroPopulation (optional)

Appending includeZeroPopulation=true, will display 0 population census locations.

curl -H"X-FullContact-APIKey:$your_key" 'http://api.fullcontact.com/v2/address/locationEnrichment.json?place=denver%20us&includeZeroPopulation=true'

casing (optional)

  • uppercase (DENVER, COLORADO)
  • lowercase (denver, colorado)
  • titlecase (Denver, Colorado)

Responses

The API responds with JSON or XML.

JSON

{
  "status": 200,
  "locations": 
  [
    {
      "city": "Las Vegas",
      "county": "Clark",
      "state": {
        "name": "Nevada",
        "code": "NV"
      },
      "country": {
        "name": "United States",
        "code": "US"
      },
      "continent": "North America",
      "population": "583756",
      "normalizedLocation": "Las Vegas, Nevada, United States"
    },
    {
      "city": "Las Vegas",
      "county": "San Miguel",
      "state": {
        "name": "New Mexico",
        "code": "NM"
      },
      "country": {
        "name": "United States",
        "code": "US"
      },
      "continent": "North America",
      "population": "13753",
      "normalizedLocation": "Las Vegas, New Mexico, United States"
    },
    {
      "city": "Las Vegas",
      "county": "Provincia De Santa Cruz De Tenerife",
      "state": {
        "name": "Canary Islands",
        "code": ""
      },
      "country": {
        "name": "Spain",
        "code": "ES"
      },
      "continent": "Europe",
      "population": "0",
      "normalizedLocation": "Las Vegas, Canary Islands, Spain"
    },
    {
      "city": "Las Vegas",
      "county": "Dimmit",
      "state": {
        "name": "Texas",
        "code": "TX"
      },
      "country": {
        "name": "United States",
        "code": "US"
      },
      "continent": "North America",
      "population": "0",
      "normalizedLocation": "Las Vegas, Texas, United States"
    }
  ]
}

XML

<?xml version="1.0" encoding="UTF-8" ?>
<location>
 <status>200</status>
 <locations>
   <location>
     <city>Las Vegas</city>
     <county>Clark</county>
     <state>
       <name>Nevada</name>
       <code>NV</code>
     </state>
     <country>
       <name>United States</name>
       <code>US</code>
     </country>
     <continent>North America</continent>
     <population>583756</population>
     <normalizedLocation>Las Vegas, Nevada, United States</normalizedLocation>
   </location>
   <location>
     <city>Las Vegas</city>
     <county>San Miguel</county>
     <state>
       <name>New Mexico</name>
       <code>NM</code>
     </state>
     <country>
       <name>United States</name>
       <code>US</code>
     </country>
     <continent>North America</continent>
     <population>13753</population>
     <normalizedLocation>Las Vegas, New Mexico, United States</normalizedLocation>
   </location>
   <location>
     <city>Las Vegas</city>
     <county>Provincia De Santa Cruz De Tenerife</county>
     <state>
       <name>Canary Islands</name>
       <code></code>
     </state>
     <country>
       <name>Spain</name>
       <code>ES</code>
     </country>
     <continent>Europe</continent>
     <population>0</population>
     <normalizedLocation>Las Vegas, Canary Islands, Spain</normalizedLocation>
   </location>
   <location>
     <city>Las Vegas</city>
     <county>Dimmit</county>
     <state>
       <name>Texas</name>
       <code>TX</code>
     </state>
     <country>
       <name>United States</name>
       <code>US</code>
     </country>
     <continent>North America</continent>
     <population>0</population>
     <normalizedLocation>Las Vegas, Texas, United States</normalizedLocation>
   </location>
 </locations>
</location>

Location API Diagram

Location Flow Diagram