openapi: 3.0.0
servers:
  - url: http://api.nytimes.com/svc/semantic/v2/geocodes
  - url: https://api.nytimes.com/svc/semantic/v2/geocodes
info:
  description: |
    The Geographic API extends the Semantic API, using a linked data approach to enhance location concepts used in The New York Times' controlled vocabulary and data resources which combine them with the GeoNames database, an authoritative and free to use database of global geographical places, names and features.
  termsOfService: http://developer.nytimes.com/tou
  title: Geographic API
  version: 1.0.0
  x-apiClientRegistration:
    url: http://developer.nytimes.com/signup
  x-apisguru-categories:
    - media
    - open_data
  x-logo:
    url: https://static01.nyt.com/images/icons/t_logo_291_black.png
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nytimes/public_api_specs/master/geo_api/geo_api_v2.json
      version: "3.0"
  x-providerName: nytimes.com
  x-serviceName: geo_api
externalDocs:
  url: http://developer.nytimes.com/
security:
  - apikey: []
paths:
  /query.json:
    get:
      description: Geographic API
      parameters:
        - description: A displayable name for the specified place.
          in: query
          name: name
          required: false
          schema:
            type: string
        - description: |
            The latitude of the specified place.
          in: query
          name: latitude
          schema:
            type: string
        - description: The longitude of the specified place.
          in: query
          name: longitude
          schema:
            type: string
        - description: The elevation of the specified place, in meters.
          in: query
          name: elevation
          required: false
          schema:
            type: integer
        - description: Along with ne, forms a bounded box using the longitude and latitude coordinates specified as the southwest corner. The search results are limited to the resulting box. Two float values, separated by a comma `latitude,longitude` <br/> The ne parameter is required to use this parameter.
          in: query
          name: sw
          required: false
          schema:
            type: string
        - description: |
            Search keywords to perform a text search on the fields: web_description, event_name and venue_name. 'AND' searches can be performed by wrapping query terms in quotes. If you do not specify a query, all results will be returned.
          in: query
          name: query
          required: false
          schema:
            type: string
        - description: |
            Filters search results based on the facets provided.  For more information on the values you can filter on, see Facets.
          in: query
          name: filter
          required: false
          schema:
            type: string
        - description: Start date to end date in the following format- YYYY-MM-DD:YYYY-MM-DD
          in: query
          name: date_range
          required: false
          schema:
            type: string
        - description: When facets is set to 1, a count of all facets will be included in the response.
          in: query
          name: facets
          schema:
            default: 0
            enum:
              - 0
              - 1
            type: integer
        - description: |
            Sorts your results on the fields specified. <br/> `sort_value1+[asc | desc],sort_value2+[asc|desc],[...]`<br/> Appending +asc to a facet or response will sort results on that value in ascending order. Appending +desc to a facet or response  will sort results in descending order. You can sort on multiple fields. You can sort on any facet. For the list of responses you can sort on, see the Sortable Field column in the Response table. <br/><br/>If you are doing a spatial search with the ll parameter, you can also sort by the distance from the center of the search: dist+[asc | desc] <br/> **Note:** either +asc or +desc is required when using the sort parameter.
          in: query
          name: sort
          schema:
            type: string
        - description: Limits the number of results returned
          in: query
          name: limit
          schema:
            default: 20
            type: integer
        - description: Sets the starting point of the result set
          in: query
          name: offset
          schema:
            default: 0
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  results:
                    items:
                      $ref: "#/components/schemas/Event"
                    type: array
                type: object
          description: An array of events
      summary: Geographic API
      tags:
        - Events
components:
  schemas:
    Event:
      properties:
        city:
          type: string
        critic_name:
          type: string
        event_detail_url:
          type: string
        event_id:
          type: integer
        event_name:
          type: string
        event_schedule_id:
          type: integer
        festival:
          type: boolean
        film_rating:
          type: boolean
        free:
          type: boolean
        kid_friendly:
          type: boolean
        last_chance:
          type: boolean
        last_modified:
          type: string
        long_running_show:
          type: boolean
        previews_and_openings:
          type: boolean
        recur_days:
          items:
            type: string
          type: array
        recurring_start_date:
          type: string
        state:
          type: string
        times_pick:
          type: boolean
        web_description:
          type: string
      type: object
  securitySchemes:
    apikey:
      in: query
      name: api-key
      type: apiKey
