The Public Location Services API provides Location Services data (Country, State, City, and ZIP) for validating location data submitted to SAM.gov. Location Services State API supports both United States and Foreign Countries. Requires a valid SAM.gov System Account API key.
openapi: 3.0.0
info:
title: SAM.gov Public Location Services API
description: >-
The SAM.gov Public Location Services API provides Location Services data including
Country, State, City, and ZIP code validation for data submitted to SAM.gov
(System for Award Management). This API requires a valid SAM.gov Federal Government
System Account API key.
version: 1.0.0
contact:
name: GSA Open Technology
url: https://open.gsa.gov/api/location-public-api/
license:
name: Creative Commons Zero (CC0)
url: https://creativecommons.org/publicdomain/zero/1.0/
servers:
- url: https://api.sam.gov
description: SAM.gov Production API
tags:
- name: Cities
description: City lookup and validation
- name: States
description: State and province lookup
- name: ZIP Codes
description: ZIP code validation
paths:
/locationservices/v1/cities:
get:
tags:
- Cities
summary: Get List of Cities
description: >-
Retrieve a list of cities for a given country code. Supports searching
by city name, active status, and city code filters. Used to validate
city data being submitted to SAM.gov.
operationId: getCities
parameters:
- name: api_key
in: query
required: true
description: SAM.gov Federal Government System Account API key
schema:
type: string
- name: cc
in: query
required: false
description: Country code (ISO 3166-1 alpha-2, e.g. US for United States)
schema:
type: string
- name: searchby
in: query
required: false
description: Field to search by (e.g. cityname, citycode)
schema:
type: string
- name: searchvalue
in: query
required: false
description: Value to search for
schema:
type: string
- name: q
in: query
required: false
description: General query string for city name search
schema:
type: string
- name: active
in: query
required: false
description: Filter to active cities only (Y/N)
schema:
type: string
enum: [Y, N]
- name: citycode
in: query
required: false
description: City code to filter by
schema:
type: string
responses:
'200':
description: Successful response with list of cities
content:
application/json:
schema:
type: object
properties:
totalRecords:
type: integer
description: Total number of matching records
cityList:
type: array
items:
type: object
properties:
cityCode:
type: string
description: City code
cityName:
type: string
description: City name
stateCode:
type: string
description: State/province code
countryCode:
type: string
description: Country code
activeInd:
type: string
description: Active indicator (Y/N)
'400':
description: Bad request - invalid parameters
'401':
description: Unauthorized - invalid or missing API key
'500':
description: Internal server error
/locationservices/v1/states:
get:
tags:
- States
summary: Get List of States and Provinces
description: >-
Retrieve a list of states, provinces, and subdivisions for both the United
States and foreign countries. Supports searching by state/province name or
code. Used to validate state data submitted to SAM.gov.
operationId: getStates
parameters:
- name: api_key
in: query
required: true
description: SAM.gov Federal Government System Account API key
schema:
type: string
- name: cc
in: query
required: false
description: Country code (ISO 3166-1 alpha-2, e.g. US for United States)
schema:
type: string
- name: searchby
in: query
required: false
description: Field to search by (e.g. statename, statecode)
schema:
type: string
- name: q
in: query
required: false
description: General query string for state name search
schema:
type: string
- name: active
in: query
required: false
description: Filter to active states/provinces only (Y/N)
schema:
type: string
enum: [Y, N]
responses:
'200':
description: Successful response with list of states/provinces
content:
application/json:
schema:
type: object
properties:
totalRecords:
type: integer
description: Total number of matching records
stateList:
type: array
items:
type: object
properties:
stateCode:
type: string
description: State/province code
stateName:
type: string
description: State/province name
countryCode:
type: string
description: Country code
activeInd:
type: string
description: Active indicator (Y/N)
'400':
description: Bad request - invalid parameters
'401':
description: Unauthorized - invalid or missing API key
'500':
description: Internal server error
/locationservices/v1/zip:
get:
tags:
- ZIP Codes
summary: Validate ZIP Code
description: >-
Validate a ZIP code and retrieve associated location data including city,
county, and state information. Used to validate ZIP code data being submitted
to SAM.gov entity registrations and procurement forms.
operationId: validateZipCode
parameters:
- name: api_key
in: query
required: true
description: SAM.gov Federal Government System Account API key
schema:
type: string
- name: zip
in: query
required: true
description: ZIP code to validate (5 digits for US postal codes)
schema:
type: string
- name: citycode
in: query
required: false
description: City code filter
schema:
type: string
- name: countycode
in: query
required: false
description: County code filter
schema:
type: string
- name: statecode
in: query
required: false
description: State code filter
schema:
type: string
responses:
'200':
description: Successful response with ZIP code validation data
content:
application/json:
schema:
type: object
properties:
zip:
type: string
description: ZIP code queried
cityList:
type: array
items:
type: object
properties:
cityCode:
type: string
cityName:
type: string
stateCode:
type: string
countyCode:
type: string
countyName:
type: string
countryCode:
type: string
'400':
description: Bad request - invalid ZIP code format
'401':
description: Unauthorized - invalid or missing API key
'404':
description: ZIP code not found
'500':
description: Internal server error