USDA SNAP Retailer Locator Retailers API

openapi: 3.2.0
info:
  title: SNAP Retailer Location Data Retailers API
  description: Esri ArcGIS Feature Service published by the USDA Food and Nutrition Administration (FNA, formerly FNS) exposing location records for every currently authorized SNAP retailer nationwide.
  version: '1.0'
  contact:
    name: USDA Food and Nutrition Administration
    url: https://www.fna.usda.gov/snap/retailer-locator
  license:
    name: Public Domain (U.S. Government Work)
    url: https://www.usa.gov/government-works
servers:
- url: https://services1.arcgis.com/RLQu0rK7h4kbsBq5/arcgis/rest/services/snap_retailer_location_data/FeatureServer
  description: USDA FNA hosted ArcGIS Feature Service (production)
tags:
- name: Retailers
  description: Query SNAP retailer location records.
paths:
  /0/query:
    get:
      operationId: queryRetailers
      tags:
      - Retailers
      summary: Query SNAP retailer locations
      description: 'Queries the SNAP retailer location layer with an optional SQL-style WHERE clause, field selection, spatial filter, sorting, distinct values, and offset-based pagination. Confirmed live: a nationwide count query (where=1=1, returnCountOnly=true) returned 254,048 authorized retailer records as of the review date; a filtered query (where=State=''DC'') returned real convenience store, grocery, and supermarket records with names and street addresses.'
      parameters:
      - name: where
        in: query
        required: false
        description: SQL-92 WHERE clause evaluated against the layer's fields, e.g. State='CA', Store_Type='Supermarket', or 1=1 to match all records.
        schema:
          type: string
          default: 1=1
      - name: outFields
        in: query
        required: false
        description: Comma-separated list of fields to return, or * for all fields.
        schema:
          type: string
          default: '*'
      - name: geometry
        in: query
        required: false
        description: Geometry (e.g. an envelope or point) to spatially filter results, used together with geometryType and spatialRel.
        schema:
          type: string
      - name: geometryType
        in: query
        required: false
        schema:
          type: string
          enum:
          - esriGeometryPoint
          - esriGeometryEnvelope
          - esriGeometryPolygon
      - name: spatialRel
        in: query
        required: false
        schema:
          type: string
          enum:
          - esriSpatialRelIntersects
          - esriSpatialRelContains
          - esriSpatialRelWithin
      - name: distance
        in: query
        required: false
        description: Buffer distance for a proximity/radius search around a point geometry.
        schema:
          type: number
      - name: units
        in: query
        required: false
        schema:
          type: string
          enum:
          - esriSRUnit_Meter
          - esriSRUnit_StatuteMile
          - esriSRUnit_Kilometer
      - name: orderByFields
        in: query
        required: false
        description: Comma-separated fields to sort by, e.g. "State ASC, City ASC".
        schema:
          type: string
      - name: returnDistinctValues
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: returnCountOnly
        in: query
        required: false
        description: If true, returns only the count of matching records instead of the records themselves.
        schema:
          type: boolean
          default: false
      - name: resultOffset
        in: query
        required: false
        description: Number of matching records to skip, for pagination.
        schema:
          type: integer
      - name: resultRecordCount
        in: query
        required: false
        description: Maximum number of records to return. The service enforces a maxRecordCount of 1,000 per request.
        schema:
          type: integer
          maximum: 1000
      - name: outSR
        in: query
        required: false
        description: Output spatial reference well-known ID. Native service SR is 102100/3857 (Web Mercator); 4326 returns WGS84 lat/lon geometry.
        schema:
          type: integer
          default: 102100
      - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Matching retailer records (or a count, if returnCountOnly=true).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
components:
  schemas:
    QueryResponse:
      type: object
      properties:
        objectIdFieldName:
          type: string
          example: ObjectId
        geometryType:
          type: string
          example: esriGeometryPoint
        spatialReference:
          type: object
          properties:
            wkid:
              type: integer
              example: 102100
        exceededTransferLimit:
          type: boolean
          description: True when more records match than were returned; page further with resultOffset.
        count:
          type: integer
          description: Present only when returnCountOnly=true.
          example: 254048
        features:
          type: array
          items:
            $ref: '#/components/schemas/QueryResponseFeature'
    Retailer:
      type: object
      description: One authorized SNAP retailer location record.
      properties:
        Record_ID:
          type: integer
        Store_Name:
          type: string
          example: Dannys Market
        Store_Street_Address:
          type: string
          example: 33 Park St
        Additonal_Address:
          type:
          - string
          - 'null'
          description: Suite/unit line, as published by the source dataset (field name misspelling is upstream-original).
        City:
          type: string
          example: Hartford
        State:
          type: string
          example: CT
        Zip_Code:
          type: string
          example: '06106'
        Zip4:
          type:
          - string
          - 'null'
          example: '2520'
        County:
          type: string
          example: CAPITOL
        Store_Type:
          type: string
          enum:
          - Convenience Store
          - Grocery Store
          - Supermarket
          - Super Store
          - Specialty Store
          - Farmers and Markets
          - Restaurant Meals Program
          - Other
        Latitude:
          type: number
          format: double
          example: 41.757061
        Longitude:
          type: number
          format: double
          example: -72.676529
        Incentive_Program:
          type:
          - string
          - 'null'
          description: Healthy Incentive Program participation, where populated.
        Grantee_Name:
          type:
          - string
          - 'null'
        ObjectId:
          type: integer
    QueryResponseFeature:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/Retailer'
        geometry:
          type: object
          properties:
            x:
              type: number
              description: X coordinate in the response spatial reference (Web Mercator by default).
            y:
              type: number
              description: Y coordinate in the response spatial reference (Web Mercator by default).
  parameters:
    Format:
      name: f
      in: query
      required: false
      description: Response format.
      schema:
        type: string
        enum:
        - json
        - geojson
        - pbf
        default: json