openapi: 3.0.3
info:
  title: NYC Geo API
  description: >
    Resolves NYC borough/neighborhood by address, zip, or borough.
    `/address` is a live lookup via NYC's Geoclient API; `/zip` and `/boro`
    read a local reference table.
  version: "1.0"
servers:
  - url: https://api.nycgeoapi.us
  - url: /

security:
  - {}
  - ApiKeyAuth: []

paths:
  /health:
    get:
      summary: Liveness check
      tags: [Meta]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: ok }

  /address:
    get:
      summary: Resolve a free-form address to borough + neighborhood
      description: Live lookup via NYC's Geoclient API. Successful results are cached for 30 days.
      tags: [Lookup]
      parameters:
        - name: houseNumber
          in: query
          required: true
          schema: { type: string }
          example: "2719"
        - name: street
          in: query
          required: true
          schema: { type: string }
          example: "Morris Avenue"
        - name: borough
          in: query
          required: true
          schema: { type: string }
          example: "Bronx"
      responses:
        "200":
          description: Resolved address
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AddressResult" }
        "400":
          description: Missing a required query param
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "422":
          description: Geoclient could not resolve the address
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429":
          $ref: "#/components/responses/RateLimited"

  /zip/{zip}:
    get:
      summary: Borough + neighborhoods for a zip code
      description: Reads the local zip/borough/neighborhood reference tables.
      tags: [Lookup]
      parameters:
        - name: zip
          in: path
          required: true
          schema: { type: string }
          example: "10468"
      responses:
        "200":
          description: Found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ZipResult" }
        "404":
          description: No data for that zip
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429":
          $ref: "#/components/responses/RateLimited"

  /boro/{borough}:
    get:
      summary: Neighborhoods for a borough
      description: Reads the local zip/borough/neighborhood reference tables.
      tags: [Lookup]
      parameters:
        - name: borough
          in: path
          required: true
          schema: { type: string }
          example: "Brooklyn"
      responses:
        "200":
          description: Found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BoroResult" }
        "404":
          description: No data for that borough
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429":
          $ref: "#/components/responses/RateLimited"

  /boro/{borough}/boundaries:
    get:
      summary: Neighborhood boundary polygons for a borough (GeoJSON)
      description: >
        For map rendering -- not part of the /boro response shape, which
        stays a plain name list. Polygons are 2020 NTA boundaries.
      tags: [Lookup]
      parameters:
        - name: borough
          in: path
          required: true
          schema: { type: string }
          example: "Brooklyn"
      responses:
        "200":
          description: Found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BoundaryFeatureCollection" }
        "404":
          description: No boundary data for that borough
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "429":
          $ref: "#/components/responses/RateLimited"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        Optional. Anonymous requests are rate-limited per IP; requests with a
        valid key get a higher per-key limit. See the project README for how
        to create one.

  responses:
    RateLimited:
      description: Rate limit exceeded for this window
      headers:
        Retry-After:
          schema: { type: integer }
          description: Seconds until the current window resets
        X-RateLimit-Limit: { schema: { type: integer } }
        X-RateLimit-Remaining: { schema: { type: integer, example: 0 } }
        X-RateLimit-Reset: { schema: { type: integer }, description: Unix timestamp }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }

  schemas:
    Error:
      type: object
      properties:
        error: { type: string }

    AddressResult:
      type: object
      properties:
        borough: { type: string, nullable: true, example: BRONX }
        neighborhood: { type: string, nullable: true, example: "Van Cortlandt Village" }
        ntaCode: { type: string, nullable: true, example: BX28 }
        latitude: { type: number, nullable: true }
        longitude: { type: number, nullable: true }

    ZipResult:
      type: object
      properties:
        zip: { type: string, example: "10468" }
        borough: { type: string, example: Bronx }
        neighborhoods:
          type: array
          items: { type: string }

    BoroResult:
      type: object
      properties:
        borough: { type: string, example: Brooklyn }
        neighborhoods:
          type: array
          items: { type: string }

    BoundaryFeatureCollection:
      type: object
      properties:
        type: { type: string, example: FeatureCollection }
        features:
          type: array
          items:
            type: object
            properties:
              type: { type: string, example: Feature }
              properties:
                type: object
                properties:
                  name: { type: string, example: "Fordham Heights" }
                  ntaCode: { type: string, nullable: true, example: BX0601 }
              geometry:
                type: object
                description: GeoJSON geometry (MultiPolygon)