{"type":"api","title":"Search GeoNames locations","meta":{"id":"/apps/pubhub/media/000-v7-apis/a9d7d077fd3cd26af5968939669b4553e8957e87/e1142937-0b87-3896-a6c5-b33ae97c352a","info":{"version":"7.0.107","title":"Endpoint Geolocation API","description":"Search for geographic locations used by Endpoint Agents."},"security":[{"BearerAuth":[]}],"tags":[{"name":"Endpoint Geolocation","description":"Search for Endpoint Agent geographic locations."}],"openapi":"3.0.1","servers":[{"description":"ThousandEyes API production URL","url":"https://api.thousandeyes.com/v7"}],"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer authentication token"}}},"spec":{"tags":["Endpoint Geolocation"],"summary":"Search GeoNames locations","operationId":"searchGeonameLocations","description":"Returns GeoNames locations that match `locationName`. If `locationName` is omitted or empty, all available locations are returned.","parameters":[{"name":"locationName","in":"query","required":false,"allowEmptyValue":true,"description":"Location name to search for. If omitted or empty, all available locations are returned.","schema":{"type":"string","default":""},"example":"London"}],"responses":{"200":{"description":"GeoNames locations matching the search criteria.","content":{"application/hal+json":{"schema":{"type":"object","description":"GeoNames locations matching the search criteria.","required":["locations","_links"],"properties":{"locations":{"type":"array","description":"Matching GeoNames locations.","items":{"type":"object","description":"A geographic location from the GeoNames catalog.","required":["geonameId","locationLevel","locationName","countryName","cityName","subdivision1Name","subdivision2Name"],"properties":{"geonameId":{"type":"string","description":"Unique GeoNames identifier for the location.","example":"2643743"},"locationLevel":{"type":"string","description":"Geographic administrative level of the location.","enum":["city","subdivision1","subdivision2","country"],"example":"city","$$ref":"#/components/schemas/GeonameLocationLevelResponse"},"locationName":{"type":"string","nullable":true,"description":"Display name of the location.","example":"London, England, UK"},"countryName":{"type":"string","nullable":true,"description":"Country containing the location.","example":"United Kingdom"},"cityName":{"type":"string","nullable":true,"description":"City containing the location. Null or empty when not applicable.","example":"London"},"subdivision1Name":{"type":"string","nullable":true,"description":"First-level administrative subdivision containing the location. Null or empty when not applicable.","example":"England"},"subdivision2Name":{"type":"string","nullable":true,"description":"Second-level administrative subdivision containing the location. Null or empty when not applicable.","example":"Greater London"}},"$$ref":"#/components/schemas/GeonameLocationResponse"}},"_links":{"type":"object","description":"A links object containing the self link.","readOnly":true,"properties":{"self":{"type":"object","description":"A hyperlink from the containing resource to a URI.","required":["href"],"properties":{"href":{"type":"string","description":"Its value is either a URI [RFC3986] or a URI template [RFC6570].","example":"https://api.thousandeyes.com/v7/link/to/resource/id"},"templated":{"type":"boolean","description":"Should be true when the link object's \"href\" property is a URI template."},"type":{"type":"string","description":"Used as a hint to indicate the media type expected when dereferencing the target resource."},"deprecation":{"type":"string","description":"Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation."},"name":{"type":"string","description":"Its value may be used as a secondary key for selecting link objects that share the same relation type."},"profile":{"type":"string","description":"A URI that hints about the profile of the target resource."},"title":{"type":"string","description":"Intended for labelling the link with a human-readable identifier"},"hreflang":{"type":"string","description":"Indicates the language of the target resource"}},"$$ref":"#/components/schemas/Link"}},"$$ref":"#/components/schemas/SelfLinks"}},"$$ref":"#/components/schemas/GeonameLocationsResponse"},"example":{"locations":[{"geonameId":"2643743","locationLevel":"city","locationName":"London, England, UK","countryName":"United Kingdom","cityName":"London","subdivision1Name":"England","subdivision2Name":"Greater London"}],"_links":{"self":{"href":"https://api.thousandeyes.com/v7/endpoint/geolocation/geonames?locationName=London"}}}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."},"errors":{"nullable":true,"type":"array","description":"(Optional) When multiple errors occur, the details for each error are listed.","items":{"type":"object","properties":{"code":{"type":"string","description":"(Optional) A unique error type/code that can be referenced in the documentation for further details."},"field":{"type":"string","description":"Identifies the field that triggered this particular error."},"message":{"type":"string","description":"A short, human-readable summary of the error."}},"$$ref":"#/components/schemas/ValidationErrorItem"}}},"$$ref":"#/components/schemas/ValidationError"},"example":{"type":"about:blank","title":"Request validation failed. There are invalid or missing fields","status":400,"detail":"Your request object contains invalid fields.","instance":"/v7","errors":[{"code":"AM-5432","field":"firstName","message":"firstName cannot have fancy characters"},{"code":"DASH-5622","field":"password","message":"Password cannot be blank"}]}}},"$$ref":"#/components/responses/400"},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid_token"},"error_description":{"type":"string","example":"Invalid access token"}},"$$ref":"#/components/schemas/UnauthorizedError"}}},"$$ref":"#/components/responses/401"},"403":{"description":"Insufficient permissions to query endpoint","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."}},"$$ref":"#/components/schemas/Error"}}},"$$ref":"#/components/responses/403"},"429":{"description":"Exhausted rate limit for the organization","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."}},"$$ref":"#/components/schemas/Error"}}},"$$ref":"#/components/responses/429"},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\"."},"title":{"type":"string","description":"A short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem."}},"$$ref":"#/components/schemas/Error"},"example":{"type":"about:blank","title":"Internal server error","status":500,"detail":"Optional detail about the internal error message.","instance":"/v7"}}},"$$ref":"#/components/responses/500"}},"__originalOperationId":"searchGeonameLocations","security":[{"BearerAuth":[]}],"method":"get","path":"/endpoint/geolocation/geonames"}}