openapi: 3.1.0
info:
  title: ESRI ArcGIS Platform Geocoding API
  description: ESRI ArcGIS Platform REST API for sharing, managing, and accessing GIS content including feature services, maps, layers, users, and portal items. The API enables geospatial data management, spatial analysis, geocoding, routing, and organizational administration for ArcGIS Online and ArcGIS Enterprise deployments.
  version: 1.0.0
  contact:
    name: ESRI Developer Support
    url: https://community.esri.com/t5/developers/ct-p/developers
  license:
    name: Esri Master Agreement
    url: https://www.esri.com/en-us/legal/terms/master-agreement
servers:
- url: https://www.arcgis.com/sharing/rest
  description: ArcGIS Online production
- url: https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer
  description: ArcGIS Geocoding Service
- url: https://route.arcgis.com/arcgis/rest/services
  description: ArcGIS Routing Service
- url: https://places-api.arcgis.com/arcgis/rest/services/v1
  description: ArcGIS Places Service
security:
- ApiKeyAuth: []
- OAuth2:
  - openid
tags:
- name: Geocoding
  description: Address search, reverse geocoding, and batch geocoding
paths:
  /findAddressCandidates:
    get:
      operationId: findAddressCandidates
      summary: Geocode an address
      description: Converts address text into geographic coordinates (forward geocoding). Returns a list of address candidates with location coordinates and match scores.
      tags:
      - Geocoding
      servers:
      - url: https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer
      parameters:
      - name: SingleLine
        in: query
        schema:
          type: string
        description: Single-line address string (e.g., "380 New York St, Redlands, CA 92373")
      - name: Address
        in: query
        schema:
          type: string
        description: Street address component
      - name: City
        in: query
        schema:
          type: string
      - name: Region
        in: query
        schema:
          type: string
        description: State or province
      - name: Postal
        in: query
        schema:
          type: string
      - name: CountryCode
        in: query
        schema:
          type: string
        description: ISO 3166-1 alpha-2 or alpha-3 country code
      - name: maxLocations
        in: query
        schema:
          type: integer
          default: 1
          maximum: 50
      - name: outFields
        in: query
        schema:
          type: string
        description: Comma-separated list of output fields (* for all)
      - name: outSR
        in: query
        schema:
          type: integer
          default: 4326
        description: Output spatial reference WKID
      - name: token
        in: query
        schema:
          type: string
      - name: f
        in: query
        schema:
          type: string
          enum:
          - json
          - pjson
          default: json
      responses:
        '200':
          description: Address candidates returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodeResponse'
  /reverseGeocode:
    get:
      operationId: reverseGeocode
      summary: Reverse geocode coordinates
      description: Converts geographic coordinates to a readable address (reverse geocoding).
      tags:
      - Geocoding
      servers:
      - url: https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer
      parameters:
      - name: location
        in: query
        required: true
        schema:
          type: string
        description: Point location as JSON (e.g., {"x":-117.2,"y":34.06,"spatialReference":{"wkid":4326}})
      - name: distance
        in: query
        schema:
          type: number
        description: Distance in meters to search from the input location
      - name: outSR
        in: query
        schema:
          type: integer
          default: 4326
      - name: token
        in: query
        schema:
          type: string
      - name: f
        in: query
        schema:
          type: string
          enum:
          - json
          - pjson
          default: json
      responses:
        '200':
          description: Reverse geocode result returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseGeocodeResponse'
components:
  schemas:
    SpatialReference:
      type: object
      properties:
        wkid:
          type: integer
          description: Well-known ID for the spatial reference (e.g., 4326 for WGS84)
        latestWkid:
          type: integer
    Point:
      type: object
      properties:
        x:
          type: number
          description: Longitude
        y:
          type: number
          description: Latitude
        spatialReference:
          $ref: '#/components/schemas/SpatialReference'
    ReverseGeocodeResponse:
      type: object
      properties:
        address:
          type: object
          properties:
            Match_addr:
              type: string
            LongLabel:
              type: string
            ShortLabel:
              type: string
            Addr_type:
              type: string
            AddNum:
              type: string
            Address:
              type: string
            City:
              type: string
            Region:
              type: string
            RegionAbbr:
              type: string
            Postal:
              type: string
            CountryCode:
              type: string
        location:
          $ref: '#/components/schemas/Point'
    GeocodeCandidate:
      type: object
      properties:
        address:
          type: string
        location:
          $ref: '#/components/schemas/Point'
        score:
          type: number
          description: Match quality score (0-100)
        attributes:
          type: object
          additionalProperties: true
    GeocodeResponse:
      type: object
      properties:
        spatialReference:
          $ref: '#/components/schemas/SpatialReference'
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/GeocodeCandidate'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: token
      description: ArcGIS API key or token
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.arcgis.com/sharing/rest/oauth2/authorize
          tokenUrl: https://www.arcgis.com/sharing/rest/oauth2/token
          scopes:
            openid: OpenID Connect identity
            urn:arcgis:scope:root: Full access to ArcGIS Online
externalDocs:
  description: ArcGIS REST API Reference
  url: https://developers.arcgis.com/rest/