Texas A&M GeoServices Geocoding API

# x-method: derived
# Authored by API Evangelist from live probes and published documentation on 2026-09-01.
# The in-file `method:` records HOW the evidence was obtained (probed / derived);
# this line records WHO WROTE THE FILE, in the provenance manifest's vocabulary.
openapi: 3.2.0
x-provenance:
  generated: '2026-09-01'
  method: derived
  source: >-
    Derived from the Texas A&M GeoServices published API reference at
    https://geoservices.tamu.edu/Services/Geocode/WebService/Details/ (HTTP 200, 2026-09-01) and
    confirmed against live anonymous calls to https://geoservices.tamu.edu/Api/Geocode/V5/ which
    returned an HTTP 200 body carrying statusCode 402 "Version Error" with no version parameter and
    statusCode 401 "APIKeyMissing" with version=5.0.0 and no apiKey. No response payload for a
    successful geocode was observed, because a successful call requires an account API key; the
    success schema below is derived from the published output-field table and is marked as such.
  x-operator: institution
info:
  title: Texas A&M GeoServices Geocoding API
  version: 5.0.0
  description: >-
    Address geocoding, address normalisation and standardisation, census intersection and reverse
    geocoding, operated by Texas A&M University at geoservices.tamu.edu. This is one of the few
    genuinely institution-engineered public APIs in the higher-education cohort: the host is under
    Texas A&M's own registrable domain, the service is a Texas A&M research product of the
    university's geospatial group, and the contract is Texas A&M's rather than a platform vendor's.

    All requests require an apiKey obtained from a free account profile. Version 5.0.0 can return up
    to 172 output fields. A parallel SOAP interface is published at
    https://geoservices.tamu.edu/Api/Geocode/V5/Soap/ and is not described here.
  contact:
    name: Texas A&M GeoServices
    url: https://geoservices.tamu.edu/Support/
  termsOfService: https://geoservices.tamu.edu/About/Legal/TermsOfUse.aspx
servers:
- url: https://geoservices.tamu.edu/Api/Geocode/V5
  description: GeoServices Geocoding API v5 production (REST)
tags:
- name: Geocoding
  description: Address to coordinate resolution with optional census intersection.
paths:
  /:
    get:
      tags:
      - Geocoding
      operationId: geocodeAddress
      summary: Geocode a US street address
      description: >-
        Resolves a non-parsed or parsed US street address to a latitude/longitude, a match type, a
        match score and an uncertainty region, optionally intersecting the result with US Census
        geographies. Verified live on 2026-09-01: an anonymous call with version=5.0.0 returns HTTP
        200 with a JSON body whose queryStatusCode is "APIKeyMissing", confirming both the parameter
        contract and the authentication model.
      security:
      - apiKeyQuery: []
      parameters:
      - name: apiKey
        in: query
        required: true
        description: API key from the GeoServices account profile page.
        schema:
          type: string
      - name: version
        in: query
        required: true
        description: API version. Omitting it returns queryStatusCode "Version Error" (402).
        schema:
          type: string
          enum: ['5.0.0']
      - name: format
        in: query
        required: false
        description: Output serialisation.
        schema:
          type: string
          enum: [json, csv, tsv, xml]
          default: json
      - name: streetAddress
        in: query
        required: false
        description: Non-parsed street address value, e.g. "1101 Texas Ave".
        schema:
          type: string
      - name: city
        in: query
        required: false
        schema:
          type: string
      - name: state
        in: query
        required: false
        schema:
          type: string
      - name: zip
        in: query
        required: false
        schema:
          type: string
      - name: census
        in: query
        required: false
        description: Calculate census variables. Slower.
        schema:
          type: boolean
          default: false
      - name: censusYears
        in: query
        required: false
        description: Comma-separated census years to intersect with, or "allAvailable".
        schema:
          type: string
          example: 2010,2020
      - name: includeHeader
        in: query
        required: false
        description: Include column headers for csv/tsv output.
        schema:
          type: boolean
      - name: notStore
        in: query
        required: false
        description: Do not historically store the transaction in the account.
        schema:
          type: boolean
      - name: verbose
        in: query
        required: false
        description: Output parsed address, matched address and reference feature details.
        schema:
          type: boolean
      - name: allowTies
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: tieBreakingStrategy
        in: query
        required: false
        schema:
          type: string
          enum: [chooseFirstOne, flipACoin, returnAll, revertToHierarchy]
          default: chooseFirstOne
      - name: confidenceLevels
        in: query
        required: false
        description: Minimum confidence level accepted for Open Addresses source matches.
        schema:
          type: integer
          minimum: 1
          maximum: 8
          default: 5
      - name: minScore
        in: query
        required: false
        description: Minimum accepted match score.
        schema:
          type: integer
          minimum: 0
          maximum: 100
      - name: exhaustiveSearch
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: aliasTables
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: attributeRelaxation
        in: query
        required: false
        schema:
          type: boolean
      - name: relaxableAttributes
        in: query
        required: false
        description: Comma-separated subset of pre, suffix, post, city, zip.
        schema:
          type: string
      - name: substringMAtching
        in: query
        required: false
        description: Spelling as published in the Texas A&M parameter table.
        schema:
          type: boolean
          default: true
      - name: soundex
        in: query
        required: false
        schema:
          type: boolean
          default: true
      - name: soundexableAttributes
        in: query
        required: false
        description: Comma-separated subset of name, city.
        schema:
          type: string
      - name: hierarchy
        in: query
        required: false
        schema:
          type: string
          enum: [uncertaintyBased, featureMatchingSelectionMethod]
          default: featureMatchingSelectionMethod
      - name: referenceDataSources
        in: query
        required: false
        schema:
          type: string
          default: all
      - name: geometry
        in: query
        required: false
        description: Return the full geometry of the reference feature. Creates a very large response.
        schema:
          type: boolean
          default: false
      - name: multithreadedGeocoder
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: outputStatistics
        in: query
        required: false
        description: Return processing statistics. json/xml only.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: >-
            Geocoding envelope. Texas A&M returns HTTP 200 for both successful and failed queries and
            carries the real outcome in statusCode / queryStatusCode inside the body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodeEnvelope'
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
      description: >-
        Free API key issued from the GeoServices account profile at
        https://geoservices.tamu.edu/Signup/. Sent as a query parameter; there is no header form.
  schemas:
    GeocodeEnvelope:
      type: object
      description: >-
        Response envelope observed live on 2026-09-01. The error shape (statusCode, message, error,
        data) was captured from a real anonymous call; the success members are derived from the
        published output-field table and were not observed, because a key is required.
      properties:
        statusCode:
          type: integer
          description: 200 on success; 401 APIKeyMissing; 402 Version Error.
          example: 401
        message:
          type: string
          example: APIKeyMissing
        error:
          type: string
          example: API Key Missing
        data:
          $ref: '#/components/schemas/GeocodeResult'
    GeocodeResult:
      type: object
      properties:
        version:
          type: object
          properties:
            major: { type: integer }
            minor: { type: integer }
            build: { type: integer }
            revision: { type: integer }
        timeTaken:
          type: number
          nullable: true
          description: Processing time in milliseconds.
        transactionGuid:
          type: string
          nullable: true
        apiHost:
          type: string
          nullable: true
        clientHost:
          type: string
          nullable: true
        queryStatusCode:
          type: string
          description: Query result code, e.g. Success, APIKeyMissing, InvalidAddress.
        inputParameterSet:
          type: object
          description: Echo of the parsed input parameters.
        outputGeocodes:
          type: array
          description: >-
            Derived from the published output-field table (positions 0-171): transaction id, api
            version, query status code, time taken, latitude, longitude, match type, matching
            geography type, micro match status, match score, region size and units, NAACCR
            coordinate quality code, and optional parsed address, matched address, reference feature
            and census intersection blocks. Not observed on a live successful call.
          items:
            type: object
externalDocs:
  description: Texas A&M GeoServices Geocoding API v5 reference
  url: https://geoservices.tamu.edu/Services/Geocode/WebService/Details/