Category filtering

The World Geocoding Service allows users to search for and geocode many different types of addresses and places around the world through a single REST endpoint. This simplifies the application building process as developers don't need to know what types of places their users are searching for, because the service can decipher that. However, due to this flexibility, it is possible for ambiguous searches to match to many different places, and users may sometimes receive unexpected results. For example, a search for a city may match to a street name, or a search for an airport code may match to a country abbreviation.

For such cases, the service provides the ability to filter out unwanted geocode results with the category parameter. The category parameter limits the types of places for which the service searches, thus eliminating false positive matches and potentially speeding up the search process.

Supported operations

The category parameter can be used with the following geocoding service operations:

When to use categories

Category filtering can be an effective way to improve geocoding and geosearch results. In general, the category parameter can be used for the following:

  • Limit matches to specific place types or address levels
  • Avoid fallback matches to unwanted address levels
  • Disambiguate coordinate searches

The following scenarios illustrate how category filtering can be used in an application.

Only match to specific place types or address levels

  • Batch geocode cities—An organization may have a list of world cities that they want to batch geocode. Streets are sometimes named after cities (such as New York Street), and because street name matches are granted priority over city name matches by the World Geocoding Service, occasionally city name input will match to a street name. Such false positive matches can be avoided by allowing the user to specify category=City in their batch geocode request. In this case, only city name records are searched, while street names and all other address and place types are ignored, ensuring that only city name matches are returned.
  • Batch geocode airport codes—Similar to the cities case, an organization may want to batch geocode a list of 3-letter airport codes. There are many other places, such as businesses and cities, that may have the same name as an airport code. Because of this, some of the airport codes in the list may unexpectedly match to other places. To ensure that only airport matches are returned, the user can specify category=Airport in the request.
  • Search for multiple restaurant types—The World Geocoding Service supports keyword searches for restaurant and other business types, such as "pizza in Redlands" or "Italian food". However, keyword search is limited such that it doesn't allow searches for both types in one request, and also may return places of a different type named "Pizza" or "Italian Food". However, with the category parameter, it's possible to search for multiple restaurant types in a single request. By passing category=Pizza,Italian Food in a request, along with a location and distance, both restaurant types will be returned if matches exist in the area of interest.

Avoid fallback matches to unwanted address levels

The World Geocoding Service supports fallback matches, meaning that it automatically geocodes to a lower match level if there is no address match for a request. For instance, if a full street address match cannot be found for a request, the service tries to find the street name. If it cannot be found, the service tries to find the postal code, then the city, and so on. If a user batch geocodes a table of addresses or stores the results of a geosearch operation and a fallback match occurs, they will be charged for the transaction even if they are not satisfied with the match.

Category filtering is the solution for this case. If category=Street Address is included in the request, only full street address matches will be returned. If one cannot be found for a particular input address, no match will be returned and the user is not charged.

Disambiguate coordinate searches

Different types of coordinates can be found by the World Geocoding Service, including MGRS (Military Grid Reference System), USNG (US National Grid), and x/y coordinates. Search for x/y coordinates can be ambiguous, because some users may place the longitude (x) coordinate first, while others may place the latitude (y) coordinate first. For instance, search for x/y coordinates 80,50 produces very different results when longitude is first than when latitude is first. Because of this ambiguity the service returns candidates in both <latitude>,<longitude> and <longitude>,<latitude> formats. However, users may want coordinates returned in a consistent format, and the category parameter can be used for this. The relevant coordinate system categories are LatLong, XY, and YX.

  • If category=YX is included in a request, then the service assumes that the coordinates are in the form <latitude>,<longitude> and returns a match in <latitude>,<longitude> format with Addr_type=YX.
  • If category=XY is included in a request, then the service assumes that the coordinates are in the form <longitude>,<latitude> and returns a match in <longitude>,<latitude> format with Addr_type=XY.
  • If category=LatLong is included in a request, the input coordinates can either be in the form <latitude>,<longitude> or <longitude>,<latitude>. The service determines the format based on the values. For example, if the coordinate pair passed in the request is -120,30, the service assumes that the coordinates are in <longitude>,<latitude> order because the value -120 is only valid as a longitude value; it returns coordinates in the same format. If an ambiguous coordinate pair is included in the request, in which both values are valid as either latitude or longitude (such as 10,10), then the service also assumes that longitude is first and returns a match in <longitude>,<latitude> format. In each case Addr_type=LatLong.
  • If none of these category values are included in a coordinate search request, or if category=Coordinate System, then all relevant matches are returned.

How to use categories

When the category parameter is passed in a request along with some search text, the World Geocoding Service performs a pre-filtering process based on the category value. This means that instead of searching through the entire stack of places and addresses for the input text, only the records that match the category value are searched, ensuring that if a matching place is found by the service, it will be the correct type of place.

Accessing category values

The category parameter works with a list of specific category values. The acceptable values for the parameter can be obtained from the World Geocoding Service description page: http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson.

Category list structure

The category list is hierarchical, meaning that there are collections of categories nested within higher level categories. The hierarchical structure simplifies the category search workflow by grouping similar categories to allow for broad searches with input of a single category value. When a high-level category value is passed in a request, it is equivalent to passing all of the category's child categories. For example, there is a top-level category named POI, which contains several child categories, such as Food and Arts and Entertainment. Each child category in turn contains many additional categories, such as African Food and Chinese Food. When category=POI is passed in a request, all of the child category values within Food and Arts and Entertainment are passed as well.

The list consists of nested JSON arrays representing child categories belonging to higher-level categories, beginning with the categories object. The abbreviated snippet below from the service description shows the categories object along with the Address category and its child categories.

"categories": [
  {
   "name": "Address",
   "localizedNames": {},
   "categories": [
    {
     "name": "Subaddress",
     "localizedNames": {}
    },
    {
     "name": "Point Address",
     "localizedNames": {}
    },
    {
     "name": "Street Address",
     "localizedNames": {}
    },
    {
     "name": "Distance Marker",
     "localizedNames": {}
    },
    {
     "name": "Intersection",
     "localizedNames": {}
    },
    {
     "name": "Street Name",
     "localizedNames": {}
    }
   ]
  },

The top-level categories object contains an array of objects representing the high-level categories; each high-level category also contains an array of child categories. Each category can include the following properties:

  • name—The category name in English. The name values are the only valid input values for the category parameter.
  • localizedNames—Reserved for a future release. The localizedNames object will contain the translated names of the category, listed by language code. The localizedNames values will only be provided as a reference for developers to create a localized user interface in their application. They will not be accepted as input for the category parameter.
  • categories—The collection of child categories associated with a particular category is stored in the categories array. If a category does not include a categories array, the category will contain no child categories.

Category filtering can be implemented in an application by incorporating the acceptable category parameter values in a user interface, allowing a user to select the desired category or categories, and then passing the values in a request.

Example implementation

The best implementation for category filtering in an application depends on the application's functionality. For most cases, the entire category hierarchy, or a portion of it, can be read from the service description and added to a list of selectable categories in a user interface. Then the categories that the user selects from the list can be passed as values for the category parameter in a request.

An example is shown below. This illustration represents a simple geosearch application in which a user can enter a search string and optionally select one or more categories from a drop-down list. The categories in the drop-down list are organized in a way that mirrors the hierarchy of categories from the list on the service description page.

Sample Category UI

In this particular case, a user is searching for amusement parks and aquariums whose names begin with "Sea". Based on the input, the application would construct the following request URL:

Request URL:

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Seaworld Adventure Park-Main Entrance",
   "location": {
    "x": -81.464289999999949,
    "y": 28.406920000000071
   },
   "score": 91.819999999999993,
   "attributes": {
    "PlaceName": "Seaworld Adventure Park-Main Entrance",
    "Type": "Amusement Park",
    "Place_addr": "Sea World Dr, Orlando, Florida, 32821",
    "City": "Orlando",
    "Region": "Florida",
    "Country": "USA"
   },
   "extent": {
    "xmin": -81.469289999999944,
    "ymin": 28.401920000000072,
    "xmax": -81.459289999999953,
    "ymax": 28.41192000000007
   }
  },
  {
   "address": "SEA Life Scheveningen",
   "location": {
    "x": 4.2791699666745364,
    "y": 52.112409981101287
   },
   "score": 86.170000000000002,
   "attributes": {
    "PlaceName": "SEA Life Scheveningen",
    "Type": "Amusement Park",
    "Place_addr": "Strandweg 13, 2586 JK Scheveningen",
    "City": "Scheveningen",
    "Region": "Zuid-Holland",
    "Country": "NLD"
   },
   "extent": {
    "xmin": 4.2739600000000406,
    "ymin": 52.107140000000065,
    "xmax": 4.2839600000000404,
    "ymax": 52.11714000000007
   }
  },

Category request details

Either a single category value or multiple comma-delimited values can be included as input in a request. When multiple values are included, the service treats the commas as OR operators and searches for all of the categories. Examples:

  • Single category: category=Sushi
  • Multiple categories: category=Sushi,Japanese Food,Mexican Food

When a high-level category is passed in a request, it is logically the same as passing all of its child categories. For instance, category=Populated Place is equivalent to category=Neighborhood,City,Subregion,Region,Country,Zone.

A request can include a value for the category parameter without a corresponding singleLine value. In this case, the highest priority or closest places that match the category will be returned.

Example: Find gas stations near Disneyland (location=-117.919120,33.812075)

Request URL:

JSON response:

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  {
   "address": "Chevron",
   "location": {
    "x": -117.91525996609754,
    "y": 33.817719977783078
   },
   "score": 100,
   "attributes": {
    "PlaceName": "Chevron",
    "Place_addr": "1200 S Harbor Blvd, Anaheim, California, 92805",
    "City": "Anaheim",
    "Region": "California"
   },
   "extent": {
    "xmin": -117.91981999999996,
    "ymin": 33.812580000000075,
    "xmax": -117.90981999999997,
    "ymax": 33.82258000000008
   }
  },
  {
   "address": "ARCO",
   "location": {
    "x": -117.92271992339431,
    "y": 33.818170066074131
   },
   "score": 100,
   "attributes": {
    "PlaceName": "ARCO",
    "Place_addr": "1037 W Ball Rd, Anaheim, California, 92802",
    "City": "Anaheim",
    "Region": "California"
   },
   "extent": {
    "xmin": -117.92768999999998,
    "ymin": 33.813360000000038,
    "xmax": -117.91768999999999,
    "ymax": 33.823360000000044
   }
  }
 ]
}

If an invalid category value is passed in a request, an error message will be returned by the service.

{
 "error": {
  "code": 400,
  "message": "Unable to complete operation.",
  "details": [
   "Category parameter value entered is not supported"
  ]
 }
}

If a category is passed for which there are no corresponding places or addresses in a country or within the map area defined by the location or searchExtent parameters, the service returns no matches.

{
 "spatialReference": {
  "wkid": 4326,
  "latestWkid": 4326
 },
 "candidates": [
  
 ]
}

Supported category values

The following table lists the entire hierarchy of supported category values. These are the same values that can be obtained from the service description page.

Note:
Not all category values are supported for all locations and countries. Efforts are being made to expand the category coverage where records for certain categories are absent.

Category level 1Category level 2Category level 3

Address

Subaddress

Point Address

Street Address

Distance Marker

Intersection

Street Name

Postal

Primary Postal

Postal Locality

Postal Extension

Coordinate System

LatLong

MGRS

XY

YX

USNG

Populated Place

Block

Sector

Neighborhood

District

City

Metro Area

Subregion

Region

Territory

Country

Zone

POI

Arts and Entertainment

Amusement Park

Aquarium

Art Gallery

Art Museum

Billiards

Bowling Alley

Casino

Cinema

Historical Monument

History Museum

Indoor Sports

Jazz Club

Landmark

Library

Live Music

Museum

Other Arts and Entertainment

Performing Arts

Ruin

Science Museum

Tourist Attraction

Wild Animal Park

Zoo

Education

College

Fine Arts School

Other Education

School

Vocational School

Food

African Food

American Food

Argentinean Food

Australian Food

Austrian Food

Bakery

BBQ and Southern Food

Belgian Food

Bistro

Brazilian Food

Breakfast

Brewpub

British Isles Food

Burgers

Cajun and Creole Food

Californian Food

Caribbean Food

Chicken Restaurant

Chilean Food

Chinese Food

Coffee Shop

Continental Food

Creperie

East European Food

Fast Food

Filipino Food

Fondue

French Food

Fusion Food

German Food

Greek Food

Grill

Hawaiian Food

Ice Cream Shop

Indian Food

Indonesian Food

International Food

Irish Food

Italian Food

Japanese Food

Korean Food

Kosher Food

Latin American Food

Malaysian Food

Mexican Food

Middle Eastern Food

Moroccan Food

Other Restaurant

Pastries

Pizza

Polish Food

Portuguese Food

Russian Food

Sandwich Shop

Scandinavian Food

Seafood

Snacks

South American Food

Southeast Asian Food

Southwestern Food

Spanish Food

Steak House

Sushi

Swiss Food

Tapas

Thai Food

Turkish Food

Vegetarian Food

Vietnamese Food

Winery

Land Features

Atoll

Basin

Butte

Canyon

Cape

Cave

Cliff

Desert

Dune

Flat

Forest

Glacier

Grassland

Hill

Island

Isthmus

Lava

Marsh

Meadow

Mesa

Mountain

Mountain Range

Oasis

Other Land Feature

Peninsula

Plain

Plateau

Point

Ravine

Ridge

Rock

Scrubland

Swamp

Valley

Volcano

Wetland

Nightlife Spot

Bar or Pub

Dancing

Karaoke

Night Club

Nightlife

Parks and Outdoors

Basketball

Beach

Campground

Diving Center

Fishing

Garden

Golf Course

Golf Driving Range

Harbor

Hockey

Ice Skating Rink

Nature Reserve

Other Parks and Outdoors

Park

Racetrack

Scenic Overlook

Shooting Range

Ski Lift

Ski Resort

Soccer

Sports Center

Sports Field

Swimming Pool

Tennis Court

Trail

Wildlife Reserve

Professional and Other Places

Ashram

Banquet Hall

Border Crossing

Building

Business Facility

Cemetery

Church

City Hall

Civic Center

Convention Center

Court House

Dentist

Doctor

Embassy

Factory

Farm

Fire Station

Government Office

Gurdwara

Hospital

Industrial Zone

Livestock

Medical Clinic

Military Base

Mine

Mosque

Observatory

Oil Facility

Orchard

Other Professional Place

Other Religious Place

Plantation

Police Station

Post Office

Power Station

Prison

Public Restroom

Radio Station

Ranch

Recreation Facility

Religious Center

Scientific Research

Shrine

Storage

Synagogue

Telecom

Temple

Tower

Veterinarian

Vineyard

Warehouse

Water Tank

Water Treatment

Residence

Estate

House

Nursing Home

Residential Area

Shops and Service

ATM

Auto Dealership

Auto Maintenance

Auto Parts

Bank

Bookstore

Butcher

Candy Store

Car Wash

Childrens Apparel

Clothing Store

Consumer Electronics Store

Convenience Store

Department Store

Electrical

Fitness Center

Flea Market

Food and Beverage Shop

Footwear

Furniture Store

Gas Station

Grocery

Home Improvement Store

Market

Mens Apparel

Mobile Phone Shop

Motorcycle Shop

Office Supplies Store

Other Shops and Service

Pet Store

Pharmacy

Plumbing

Repair Services

Shopping Center

Spa

Specialty Store

Sporting Goods Store

Tire Store

Toy Store

Used Car Dealership

Wholesale Warehouse

Womens Apparel

Travel and Transport

Airport

Bed and Breakfast

Bridge

Bus Station

Cargo Center

Dock

Ferry

Heliport

Highway Exit

Hostel

Hotel

Marina

Metro Station

Motel

Other Travel

Parking

Pier

Port

Railyard

Rental Cars

Resort

Rest Area

Taxi

Tourist Information

Train Station

Transportation Service

Truck Stop

Tunnel

Water Features

Bay

Canal

Channel

Cove

Dam

Delta

Estuary

Fjord

Gulf

Hot Spring

Irrigation

Jetty

Lagoon

Lake

Ocean

Other Water Feature

Reef

Reservoir

Sea

Sound

Spring

Strait

Stream

Waterfall

Well

Wharf