swagger: '2.0'
basePath: /svc/semantic/v2/geocodes
host: api.nytimes.com
info:
  version: 1.0.0
  title: Geographic API
  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.
schemes:
  - http
  - https

produces:
  - application/json
security:
  - apikey: []
paths:
  /query.json:
    get:
      summary: Geographic API
      description: Geographic API
      parameters:
        - name: name
          in: query
          description: A displayable name for the specified place.
          type: string
          required: false
        - name: latitude
          in: query
          description: |
            The latitude of the specified place.
          type: string
        - name: longitude
          in: query
          description: The longitude of the specified place.
          type: string
        - name: elevation
          in: query
          description: 'The elevation of the specified place, in meters.'
          type: integer
          required: false
        - name: sw
          in: query
          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.'
          type: string
          required: false
        - name: query
          in: query
          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.
          type: string
          required: false
        - name: filter
          in: query
          description: |
            Filters search results based on the facets provided.  For more information on the values you can filter on, see Facets.
          type: string
          required: false
        - name: date_range
          in: query
          description: 'Start date to end date in the following format- YYYY-MM-DD:YYYY-MM-DD'
          type: string
          required: false
        - name: facets
          in: query
          description: 'When facets is set to 1, a count of all facets will be included in the response.'
          type: integer
          default: 0
          enum:
            - 0
            - 1
        - name: sort
          in: query
          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.
          type: string
        - name: limit
          in: query
          description: Limits the number of results returned
          type: integer
          default: 20
        - name: offset
          in: query
          description: Sets the starting point of the result set
          type: integer
          default: 0
      tags:
        - Events
      responses:
        '200':
          description: An array of events
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  $ref: '#/definitions/Event'
definitions:
  Event:
    type: object
    properties:
      event_id:
        type: integer
      event_schedule_id:
        type: integer
      last_modified:
        type: string
      event_name:
        type: string
      event_detail_url:
        type: string
      web_description:
        type: string
      city:
        type: string
      state:
        type: string
      film_rating:
        type: boolean
      critic_name:
        type: string
      times_pick:
        type: boolean
      free:
        type: boolean
      kid_friendly:
        type: boolean
      last_chance:
        type: boolean
      festival:
        type: boolean
      long_running_show:
        type: boolean
      previews_and_openings:
        type: boolean
      recurring_start_date:
        type: string
      recur_days:
        type: array
        items:
          type: string
securityDefinitions:
  apikey:
    type: apiKey
    name: api-key
    in: query