openapi: 3.0.0
info:
  title: DuckDuckGo Maps API
  description: |
    DuckDuckGo Maps API returns the places DuckDuckGo Maps shows for a search, with their address, GPS coordinates, phone, website, rating, reviews, opening hours, amenities, photos and review snippets. Places come from Yelp, Tripadvisor or Apple Maps, as DuckDuckGo shows them. A search returns up to about 20 places. When the query names a city or a region with no places, the response describes that area in `place_result`.

    Every search needs one of `location`, `lat` and `lon`, or `bounding_box`, even when `q` names a place. A place named in `q` (for example `coffee shops in brooklyn`) can move the search there, and an ambiguous name such as `springfield` is usually read as the one nearest that location. With `bounding_box`, every place is inside the box.

    **Cross-linking**: Pass `apple_maps_place_id` to the Apple Maps Places API as `place_ids`, `yelp_place_id` to the Yelp Place API or the Yelp Reviews API as `place_id`, and `tripadvisor_place_id` to the Tripadvisor Place API or the Tripadvisor Reviews API as `place_id`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: DuckDuckGo Maps Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to duckduckgo_maps
          schema:
            type: string
            enum: ["duckduckgo_maps"]
        - name: q
          in: query
          required: true
          description: Search query, optionally naming the place to search in (for example coffee shops in brooklyn)
          schema:
            type: string
            maxLength: 500
        - name: location
          in: query
          required: false
          description: Location to search around, as a city, region or country name. One of location, lat and lon, or bounding_box is required, and location can't be used with the others.
          schema:
            type: string
            maxLength: 200
        - name: lat
          in: query
          required: false
          description: Latitude of the point to search around. One of location, lat and lon, or bounding_box is required; lat needs lon and can't be used with location or bounding_box.
          schema:
            type: number
            minimum: -90
            maximum: 90
        - name: lon
          in: query
          required: false
          description: Longitude of the point to search around. One of location, lat and lon, or bounding_box is required; lon needs lat and can't be used with location or bounding_box.
          schema:
            type: number
            minimum: -180
            maximum: 180
        - name: bounding_box
          in: query
          required: false
          description: 'Area to search in, as four decimal degrees west,south,east,north (for example -74.01,40.70,-73.95,40.76), with or without square brackets. The two latitudes can come in either order, so the bbox value of a DuckDuckGo Maps URL works as is. Each side spans at most 60 degrees, and the area can''t cross the antimeridian. Every place returned is inside the box; in a large box DuckDuckGo picks which places come back, and can return few places or none. One of location, lat and lon, or bounding_box is required, and bounding_box can''t be used with the others.'
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        local_results:
          type: array
          description: Places DuckDuckGo Maps returned for the search, up to about 20
          items:
            $ref: '#/components/schemas/LocalResult'
        place_result:
          $ref: '#/components/schemas/PlaceResult'
        error:
          type: string
          description: Message explaining why the search returned no places
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          nullable: true
          description: DuckDuckGo Maps URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        q:
          type: string
          description: Search query
        location:
          type: string
          description: Location requested in the location parameter
        location_used:
          type: string
          description: Full name of the location the search used
        lat:
          type: string
          description: Latitude of the point searched around
        lon:
          type: string
          description: Longitude of the point searched around
        bounding_box:
          type: string
          description: Area searched in
    SearchInformation:
      type: object
      properties:
        query_displayed:
          type: string
          description: Query DuckDuckGo searched for
    LocalResult:
      type: object
      required: [position, title]
      properties:
        position:
          type: integer
          description: Position of the place in the results
        title:
          type: string
          description: Name of the place
        source:
          type: string
          description: Provider DuckDuckGo shows the place from (Yelp, Tripadvisor or Apple Maps)
        link:
          type: string
          description: Link to the place on its provider
        apple_maps_place_id:
          type: string
          description: Apple Maps place ID of the place, accepted by the Apple Maps Places API as place_ids
        yelp_place_id:
          type: string
          description: Yelp business ID, accepted by the Yelp Place and Yelp Reviews APIs as place_id
        tripadvisor_place_id:
          type: string
          description: Tripadvisor location ID, accepted by the Tripadvisor Place and Tripadvisor Reviews APIs as place_id
        address:
          type: string
          description: Street address of the place
        city:
          type: string
          description: City of the place
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code of the place
        neighborhoods:
          type: array
          description: Neighborhoods the place is in
          items:
            type: string
        gps_coordinates:
          $ref: '#/components/schemas/GpsCoordinates'
        distance:
          type: integer
          description: Distance in meters from the point given in location or lat and lon
        phone:
          type: string
          description: Phone number in international format
        phone_formatted:
          type: string
          description: Phone number formatted for display
        website:
          type: string
          description: Website of the place
        rating:
          type: number
          description: Rating out of 5 from the place's provider
        reviews:
          type: integer
          description: Number of reviews behind the rating
        price_score:
          type: integer
          description: Price level from 1 (least expensive) to 4
        type:
          type: string
          description: Primary category of the place
        types:
          type: array
          description: Categories of the place
          items:
            type: string
        is_permanently_closed:
          type: boolean
          description: Whether the place has closed for good
        open_state:
          type: string
          description: Open status of the place when the search ran
          enum: ["open", "closed", "closing_soon", "opening_soon"]
        open_hours:
          $ref: '#/components/schemas/OpenHours'
        timezone:
          type: string
          description: IANA timezone of the place
        amenities:
          type: array
          description: Amenities the place offers
          items:
            type: string
            enum: ["dogs_allowed", "outdoor_seating", "parking", "parking_paid", "parking_valet", "restaurant_delivery", "restaurant_takeout", "wheelchair_accessible", "wifi_free", "wifi_paid"]
        thumbnail:
          type: string
          description: Main photo of the place
        images:
          type: array
          description: Photos of the place
          items:
            type: string
        images_link:
          type: string
          description: Link to the place's photo gallery on its provider
        menu_link:
          type: string
          description: Link to the place's menu
        user_reviews:
          type: array
          description: Review snippets DuckDuckGo shows for the place
          items:
            $ref: '#/components/schemas/UserReview'
    GpsCoordinates:
      type: object
      required: [latitude, longitude]
      properties:
        latitude:
          type: number
          description: Latitude of the place
        longitude:
          type: number
          description: Longitude of the place
    OpenHours:
      type: object
      description: Opening hours keyed by weekday, each day an array of 24-hour ranges written as two HH:MM times joined by an en dash
      properties:
        monday:
          type: array
          items:
            type: string
        tuesday:
          type: array
          items:
            type: string
        wednesday:
          type: array
          items:
            type: string
        thursday:
          type: array
          items:
            type: string
        friday:
          type: array
          items:
            type: string
        saturday:
          type: array
          items:
            type: string
        sunday:
          type: array
          items:
            type: string
    UserReview:
      type: object
      required: [snippet]
      properties:
        review_id:
          type: string
          description: ID of the review on its provider
        link:
          type: string
          description: Link to the review on its provider
        snippet:
          type: string
          description: Beginning of the review text
        rating:
          type: integer
          description: Rating the reviewer gave, out of 5
        iso_date:
          type: string
          format: date-time
          description: Date the review was written
        user:
          $ref: '#/components/schemas/ReviewUser'
    ReviewUser:
      type: object
      properties:
        name:
          type: string
          description: Name of the reviewer
        link:
          type: string
          description: Link to the reviewer's profile
        thumbnail:
          type: string
          description: Reviewer's profile photo
    PlaceResult:
      type: object
      required: [title]
      properties:
        title:
          type: string
          description: Name of the area
        region:
          type: string
          description: Region the area is in
        country:
          type: string
          description: Country the area is in
        gps_coordinates:
          $ref: '#/components/schemas/GpsCoordinates'
        bounds:
          $ref: '#/components/schemas/Bounds'
    Bounds:
      type: object
      properties:
        north_latitude:
          type: number
          description: Latitude of the northern edge
        south_latitude:
          type: number
          description: Latitude of the southern edge
        east_longitude:
          type: number
          description: Longitude of the eastern edge
        west_longitude:
          type: number
          description: Longitude of the western edge
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong