sam-gov-location-services-openapi.yml

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