Back to top

Search API

The main purpose of this API is to provide methods to search and retrieve documents and influencers. The influencers search is based on the publications written by himself. Using this API you cannot search influencers by name or by other fields not related to the publications (you can use the Influencers Profile API instead).

This API is not intended for real-time document pulling

The production url for this API is https://nap.launchmetrics.com/search/v1

Authentication

All apis contain the /v[:version] placeholder. It’s used to do API versioning

  • v0 For testing environments, no authentication is required and it’s disabled on production

  • v1 Production version, authentication required

There are two ways to authenticate the request

  • with just an app_id parameter (if you don’t have an app_id you should request one) (less secure)

  • with an app_id + signature parameters (signature creation explained below) (more secure)

The use of appId or appid is deprecated, use app_id instead

The testing environment is not up 24/7, so some calls to the testing urls may return 404

Create a signature

This method is inspired from https://dev.twitter.com/docs/auth/creating-signature

To sign a request you need:

  • http method in uppercase: GET, POST

  • Request url without parameters

  • The parameter string, a url-encoded and sorted parameters string (see below to know how to generate it)

  • Body bytes content, if you’re not sending form data

  • Current timestamp (in seconds)

  • A nonce, in other words, a random string which have at least 32 characters

  • An app_id provided by R&D

  • A secret (related to the app) provided by R&D

For example, given this parameters as key and values:

{ “query”: “girona”, "period: “last_month”, }

Step 1, add the timestampp, nonce and app_id:

{ “query”: “girona”, “period”: “last_month”, “timestamp”: “1380545928”, “nonce”: “QC3hTWyVby6PtKKeCnxPAEMPXebUP82D”, “app_id”: “3ttp2946sij2hic” }

Step 2, percent encode all keys and values

{ “query”: “girona”, “period”: “last_month”, “timestamp”: “1380545928”, “nonce”: “QC3hTWyVby6PtKKeCnxPAEMPXebUP82D”, “app_id”: “3ttp2946sij2hic” }

Make sure your percent encode library encode spaces as %20 instead of +. Using the + sign will generate an incorrect signature.

Step 3, join the key and value using a = and sort the parameters alphabetically

[ “app_id=3ttp2946sij2hic”, “nonce=QC3hTWyVby6PtKKeCnxPAEMPXebUP82D”, “period=last_month”, “query=girona”, “timestamp=1380545928” ]

Step 4, join all parameters with & to generate the parameter_string

app_id=3ttp2946sij2hic&nonce=QC3hTWyVby6PtKKeCnxPAEMPXebUP82D&period=last_month&query=girona&timestamp=1380545928

Step 5, generate the signature_base string using this schema

signature_base = http_method&url_encoded(request_url)&url_encoded(parameter_string)

Step 6, if you’re sending not form data on body(p.e. a json or plain text), add body bytes after a new line

signature_base = signature_base + “\n” + ‘{“json”: “example”}’

where

  • http_method is the http method used for the request in uppercase: GET

  • request_url is the url without parameters and without the protocol, for example nap.aws.augure.com/v1/search/influencers

  • parameter_string is explained above, for example app_id=3ttp2946sij2hic&nonce=QC3hTWyVby6PtKKeCnxPAEMPXebUP82D&period=last_month&query=girona&timestamp=1380545928

Then the signature_base string will be:

GET&nap.aws.augure.com%2Fv1%2Fsearch%2Finfluencers&app_id%3D3ttp2946sij2hic%26nonce%3DQC3hTWyVby6PtKKeCnxPAEMPXebUP82D%26period%3Dlast_month%26query%3Dgirona%26timestamp%3D1380545928 {“json”: “example”}

don’t forget to url_encode the request_url and the parameter_string

Step 6, generate the signature parameter using the HMAC_SHA1 algorithm. This algorithm needs 2 strings to work, the first one will be the signature_base string, and the second one will be the secret (needed to generate the secure hash).

The output of this algorithm is binary, so you should use base64 encoding to produce the final signature string.

If the secret provided for our app is rpii62atrbqejx27v7uv32qbn8exv7gj then the signature of our request will be

OHQRsFL3dqFIStxxHcv1yY8qcy4=

Step 7, add the signature value to the request parameters and execute the request to the API. In this case will be

{ “query”: “girona”, “period”: “last_month”, “nonce”: “QC3hTWyVby6PtKKeCnxPAEMPXebUP82D”, “timestamp”: “1380545928”, “app_id”: “3ttp2946sij2hic”, “signature”: “OHQRsFL3dqFIStxxHcv1yY8qcy4=” }

Don’t forget, if you’re not using a helper library, you should url encode all keys and values.

For the POST and PUT requests which you’re not sending form data, like a json or plain text, the parameters related to the signature must be added to the url, p.e.: https://nap.launchmetrics.com/v1/analysis?app_id=xxx&nonce=xxx&timestamp=xxx&signature=xxx

Response

All responses return application/json; charset=utf-8.

  • Response ok (application/json)

    The response element will contain the specific API method response.

    {
        "status": "200",
        "time": "0.2",
        "request": {
          "method":"GET",
          "path":"/ping",
          "parameters": {}
      },
      "response": {}
    }

  • Response error (application/json)

    There could be different messages with the correspondent HTTP error code.

    {
        "status": "404",
        "time": "0.2",
        "request": {
          "method":"GET",
          "path":"/ping",
          "parameters": {}
      },
      "error": {
        "code": "WRONG_PARAMETERS",
        "message": "The email parameter is mandatory"
      }
    }

Generic Error codes

  • Http status 400

    • MISSING_PARAMETERS

      Some error with the API parameters

  • Http status 500

    • INTERNAL_ERROR

      Unexpected API error

API Health

There are two default methods available for each API for monitoring purposes.

Ping

Ping
GET/ping

Used to know if the API is up and working

Example URI

GET https://nap.launchmetrics.com/search/v1/ping
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "pong": "ok"
}

Stats

Stats
GET/stats

It displays information about the API usage and how it performs

Example URI

GET https://nap.launchmetrics.com/search/v1/stats
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "last24hours": {
    "GET /emailValidation/v1/setEmailStatus": {
      "hour_interval": [
        {
          "hour": "2016-02-18T16:00:00.000Z",
          "count": 2,
          "variance": 0,
          "status": {
            "EMAIL_NOT_FOUND": {
              "count": 2,
              "variance": 0,
              "std_deviation": 0,
              "avg": 0.168862000107765,
              "min": 0.168862000107765,
              "max": 0.168862000107765,
              "sum_of_squares": 0.0570287501607898,
              "std_deviation_bounds": {
                "upper": 0.168862000107765,
                "lower": 0.168862000107765
              },
              "sum": 0.33772400021553
            },
            "OK": {
              "count": 0,
              "variance": null,
              "std_deviation": null,
              "avg": null,
              "min": null,
              "max": null,
              "sum_of_squares": null,
              "std_deviation_bounds": {
                "upper": null,
                "lower": null
              },
              "sum": null
            }
          },
          "min": 0.168862000107765,
          "avg": 0.168862000107765,
          "std_deviation": 0,
          "max": 0.168862000107765,
          "sum_of_squares": 0.0570287501607898,
          "sum": 0.33772400021553,
          "std_deviation_bounds": {
            "upper": 0.168862000107765,
            "lower": 0.168862000107765
          }
        },
        {
          "hour": "2016-02-18T18:00:00.000Z",
          "count": 2,
          "variance": 0,
          "status": {
            "EMAIL_NOT_FOUND": {
              "count": 2,
              "variance": 0,
              "std_deviation": 0,
              "avg": 0.0233999993652105,
              "min": 0.0233999993652105,
              "max": 0.0233999993652105,
              "sum_of_squares": 0.00109511994058371,
              "std_deviation_bounds": {
                "upper": 0.0233999993652105,
                "lower": 0.0233999993652105
              },
              "sum": 0.0467999987304211
            },
            "OK": {
              "count": 0,
              "variance": null,
              "std_deviation": null,
              "avg": null,
              "min": null,
              "max": null,
              "sum_of_squares": null,
              "std_deviation_bounds": {
                "upper": null,
                "lower": null
              },
              "sum": null
            }
          },
          "min": 0.0233999993652105,
          "avg": 0.0233999993652105,
          "std_deviation": 0,
          "max": 0.0233999993652105,
          "sum_of_squares": 0.00109511994058371,
          "sum": 0.0467999987304211,
          "std_deviation_bounds": {
            "upper": 0.0233999993652105,
            "lower": 0.0233999993652105
          }
        },
        {
          "hour": "2016-02-18T20:00:00.000Z",
          "count": 2,
          "variance": 0,
          "status": {
            "EMAIL_NOT_FOUND": {
              "count": 2,
              "variance": 0,
              "std_deviation": 0,
              "avg": 0.0268389992415905,
              "min": 0.0268389992415905,
              "max": 0.0268389992415905,
              "sum_of_squares": 0.00144066376058019,
              "std_deviation_bounds": {
                "upper": 0.0268389992415905,
                "lower": 0.0268389992415905
              },
              "sum": 0.053677998483181
            },
            "OK": {
              "count": 0,
              "variance": null,
              "std_deviation": null,
              "avg": null,
              "min": null,
              "max": null,
              "sum_of_squares": null,
              "std_deviation_bounds": {
                "upper": null,
                "lower": null
              },
              "sum": null
            }
          },
          "min": 0.0268389992415905,
          "avg": 0.0268389992415905,
          "std_deviation": 0,
          "max": 0.0268389992415905,
          "sum_of_squares": 0.00144066376058019,
          "sum": 0.053677998483181,
          "std_deviation_bounds": {
            "upper": 0.0268389992415905,
            "lower": 0.0268389992415905
          }
        }
      ],
      "count": 2068,
      "variance": 0.952526547318981,
      "min": 18.1012001037598,
      "avg": 19.8605297686284,
      "std_deviation": 0.975974665305909,
      "max": 23.6008319854736,
      "sum_of_squares": 817673.073983961,
      "std_deviation_bounds": {
        "upper": 21.8124790992402,
        "lower": 17.9085804380165
      },
      "sum": 41071.5755615234
    }
  },
  "last15days": {
    "GET /emailValidation/v1/setServerEmailsVerificationPending": {
      "count": 1,
      "variance": 0,
      "min": 28.7900829315186,
      "avg": 28.7900829315186,
      "std_deviation": 0,
      "max": 28.7900829315186,
      "sum_of_squares": 828.868875203716,
      "day_interval": [
        {
          "count": 1,
          "variance": 0,
          "status": {
            "CONNECTION_ERROR": {
              "count": 1,
              "variance": 0,
              "std_deviation": 0,
              "avg": 28.7900829315186,
              "min": 28.7900829315186,
              "max": 28.7900829315186,
              "sum_of_squares": 828.868875203716,
              "std_deviation_bounds": {
                "upper": 28.7900829315186,
                "lower": 28.7900829315186
              },
              "sum": 28.7900829315186
            },
            "OK": {
              "count": 0,
              "variance": null,
              "std_deviation": null,
              "avg": null,
              "min": null,
              "max": null,
              "sum_of_squares": null,
              "std_deviation_bounds": {
                "upper": null,
                "lower": null
              },
              "sum": null
            }
          },
          "min": 28.7900829315186,
          "avg": 28.7900829315186,
          "std_deviation": 0,
          "max": 28.7900829315186,
          "sum_of_squares": 828.868875203716,
          "day": "2016-02-07T00:00:00.000Z",
          "sum": 28.7900829315186,
          "std_deviation_bounds": {
            "upper": 28.7900829315186,
            "lower": 28.7900829315186
          }
        }
      ],
      "std_deviation_bounds": {
        "upper": 28.7900829315186,
        "lower": 28.7900829315186
      },
      "sum": 28.7900829315186
    }
  }
}

Custom error codes

Http status 400

  • SEARCH_MISSING_PARAMETERS

    Missing search parameters

  • WRONG_PARAMETERS

    Will appear if sort is not correctly passed

  • SEARCH_DATE_PROBLEM

    Search range must be specified via period parameter, or with begin_date and end_date paremeters. Missing begin_date or end_date parameter

  • SEARCH_INVALID_RESPONSE_TYPE

  • SEARCH_INVALID_PERIOD

  • SEARCH_INVALID_LIMIT_VALUE

  • SEARCH_INVALID_LIMIT

  • SEARCH_INVALID_DATES

    When date format is not valid

    Date format must be ISO8601 with leading Z for UTC, or UTC offset

    Some valid dates:

  2015-05-03T15:38:45Z
  2015-05-03T15:38:45+00:00
  2015-05-03T16:38:45+01:00
  2015-05-03T14:38:45-01:00

  • SEARCH_INVALID_SHOW_FACETS

  • SEARCH_INVALID_FACET_FIELDS

  • ERROR_IN_QUERY

    There is some syntax error in query

Http status 500

  • SEARCH_FAILED

    It could be triggered if the search query is not well formed.

    Also, there is a default timeout of 30s on all requests, after that period, the request will return a SEARCH_FAILED status

Search Collection

Available fields

We didn’t change the index schema to ease the transition from the previous one managed by París to the current one.

For filtering purposes, all available fields are:

audience
channel_type_id [see below for more info]
cluster [0 if the document is unique, otherwise it contain the father document's id]
content
country_path    [see below for more info]
shares
likes
replies
views
influencer_ids
key_phrases     [extracted from Alchemy]
language_id     [see below for more info]
publication_date
media_id
section_id
signature_id    [author identifier from each document]
title
topic_paths     [see below for more info]
has_gallery
users_in_photo
tags
mentions
gallery.source_id    [parent document id]

  • Channel_type_id values

    • 0 Online media
    • 1 Blogs
    • 2 Press Releases/Agencies
    • 3 Official newsletters
    • 4 Corporate
    • 5 Portals/Searchers
    • 12 Classified blogs
    • 30 Twitter
    • 40 Youtube
    • 50 Flickr
    • 51 Instagram
    • 60 Facebook
    • 61 Linkedin
    • 80 Radio

  • Language_id values

    • 0 spanish
    • 1 catalan
    • 2 english
    • 3 french
    • 4 german
    • 5 basque
    • 6 galician
    • 7 portuguese
    • 8 italian
    • 9 swedish
    • 10 dutch
    • 11 danish
    • 12 asturian
    • 13 afar
    • 14 abkhazian
    • 15 avestan
    • 16 afrikaans
    • 17 akan
    • 18 amharic
    • 19 aragonese
    • 20 arabic
    • 21 assamese
    • 22 avaric
    • 23 aymara
    • 24 azerbaijani
    • 25 bashkir
    • 26 belarusian
    • 27 bulgarian
    • 28 bihari languages
    • 29 bislama
    • 30 bambara
    • 31 bengali
    • 32 tibetan
    • 33 breton
    • 34 bosnian
    • 36 chechen
    • 37 chamorro
    • 38 corsican
    • 39 cree
    • 40 czech
    • 41 church slavic; old slavonic; church slavonic; old bulgarian; old church slavonic
    • 42 chuvash
    • 43 welsh
    • 46 divehi; dhivehi; maldivian
    • 47 dzongkha
    • 48 ewe
    • 49 greek, modern (1453-)
    • 51 esperanto
    • 53 estonian
    • 55 persian
    • 56 fulah
    • 57 finnish
    • 58 fijian
    • 59 faroese
    • 61 western frisian
    • 62 irish
    • 63 gaelic; scottish gaelic
    • 65 guarani
    • 66 gujarati
    • 67 manx
    • 68 hausa
    • 69 hebrew
    • 70 hindi
    • 71 hiri motu
    • 72 croatian
    • 73 haitian; haitian creole
    • 74 hungarian
    • 75 armenian
    • 76 herero
    • 77 interlingua (international auxiliary language association)
    • 78 indonesian
    • 79 interlingue; occidental
    • 80 igbo
    • 81 sichuan yi; nuosu
    • 82 inupiaq
    • 83 ido
    • 84 icelandic
    • 86 inuktitut
    • 87 japanese
    • 88 javanese
    • 89 georgian
    • 90 kongo
    • 91 kikuyu; gikuyu
    • 92 kuanyama; kwanyama
    • 93 kazakh
    • 94 kalaallisut; greenlandic
    • 95 central khmer
    • 96 kannada
    • 97 korean
    • 98 kanuri
    • 99 kashmiri
    • 100 kurdish
    • 101 komi
    • 102 cornish
    • 103 kirghiz; kyrgyz
    • 104 latin
    • 105 luxembourgish; letzeburgesch
    • 106 ganda
    • 107 limburgan; limburger; limburgish
    • 108 lingala
    • 109 lao
    • 110 lithuanian
    • 111 luba-katanga
    • 112 latvian
    • 113 malagasy
    • 114 marshallese
    • 115 maori
    • 116 macedonian
    • 117 malayalam
    • 118 mongolian
    • 119 marathi
    • 120 malay
    • 121 maltese
    • 122 burmese
    • 123 nauru
    • 124 bokmål, norwegian; norwegian bokmål
    • 125 ndebele, north; north ndebele
    • 126 nepali
    • 127 undefined
    • 129 norwegian nynorsk; nynorsk, norwegian
    • 130 norwegian
    • 131 ndebele, south; south ndebele
    • 132 navajo; navaho
    • 133 chichewa; chewa; nyanja
    • 134 occitan (post 1500)
    • 135 ojibwa
    • 136 oromo
    • 137 oriya
    • 138 ossetian; ossetic
    • 139 panjabi; punjabi
    • 140 pali
    • 141 polish
    • 142 pushto; pashto
    • 144 quechua
    • 145 romansh
    • 146 rundi
    • 147 romanian; moldavian; moldovan
    • 148 russian
    • 149 kinyarwanda
    • 150 sanskrit
    • 151 sardinian
    • 152 sindhi
    • 153 northern sami
    • 154 sango
    • 155 sinhala; sinhalese
    • 156 slovak
    • 157 slovenian
    • 158 samoan
    • 159 shona
    • 160 somali
    • 161 albanian
    • 162 serbian
    • 163 swati
    • 164 sotho, southern
    • 165 sundanese
    • 167 swahili
    • 168 tamil
    • 169 telugu
    • 170 tajik
    • 171 thai
    • 172 tigrinya
    • 173 turkmen
    • 174 tagalog
    • 175 tswana
    • 176 tonga (tonga islands)
    • 177 turkish
    • 178 tsonga
    • 179 tatar
    • 180 twi
    • 181 tahitian
    • 182 uighur; uyghur
    • 183 ukrainian
    • 184 urdu
    • 185 uzbek
    • 186 venda
    • 187 vietnamese
    • 188 volapük
    • 189 walloon
    • 190 wolof
    • 191 xhosa
    • 192 yiddish
    • 193 yoruba
    • 194 zhuang; chuang
    • 195 chinese
    • 196 zulu
    • 197 ndonga

  • Topic_path values

    • A1 Art & Culture
    • A101 Architecture
    • A102 Cinema & Video
    • A103 Dance
    • A104 Books & Literature
    • A105 Music
    • A106 Photography
    • A107 Theatre
    • A108 Art
    • A109 Culture
    • A110 Sculpture
    • A111 Museums & Galleries
    • A112 Painting
    • A113 Comic
    • A114 Design
    • A2 Medicine and Health
    • A201 Alternative medicine
    • A202 Public Health
    • A203 Pharmacology & Therapeutics
    • A204 Veterinary medicine
    • A205 Organizations
    • A206 Illnesses
    • A207 Mental Health
    • A208 Health
    • A209 Medicine
    • A3 Sports
    • A301 American Football
    • A302 Athletics
    • A303 Baseball
    • A304 Basketball
    • A305 Combat sports
    • A306 Cricket
    • A307 Cycling
    • A308 Hockey
    • A309 Skating sports
    • A310 Winter & mountain sports
    • A311 Golf
    • A312 Handball
    • A313 Equestrian sports
    • A314 Motorcycling
    • A315 Football / Soccer
    • A316 Olympic Games
    • A317 Tennis & other raquet sports
    • A318 Volleyball
    • A319 Aquatic sports
    • A320 Extreme sports
    • A321 Associations & competitions
    • A322 Clubs / Sport Teams
    • A323 Rugby
    • A324 Gymnastics
    • A4 Leisure / Free time
    • A401 Hobbies & Collecting
    • A402 Gastronomy
    • A403 Games
    • A404 Tourism / Travel / Trips
    • A405 Humour
    • A406 Video games
    • A407 Home / Garden
    • A5 Society
    • A501 Folklore & Traditional Festivals
    • A502 LGBT
    • A503 Celebrities & Gossip
    • A504 family (elderly, youth, family, children)
    • A505 Religion
    • A506 Pets / domestic animals
    • A507 NGOs, Solidarity and Associations
    • A508 Education
    • A509 Consumption
    • A6 Sciences
    • A601 Space science
    • A602 Biology
    • A603 Social Science
    • A604 Physics & Chemistry
    • A605 Mathematics
    • A606 Earth sciences
    • A607 Psychology
    • A608 Science
    • A609 Engineering & technology
    • A610 Medicine
    • A611 Philosophy, History & other human sciences
    • A7 Industry
    • A701 Graphic Arts & Audio-visual
    • A702 Agriculture / Stock breeding / Fishing
    • A703 Food / Drink
    • A704 Construction & Public Works
    • A705 Energy
    • A706 Hotels & Restaurants
    • A707 Transport & Logistics
    • A708 Real estate agencies
    • A709 Engineering and Mechanics
    • A710 Security
    • A8 Technology & Internet
    • A801 Software
    • A802 Hardware
    • A803 Cybersecurity
    • A804 Networks & Telecommunications
    • A805 Technology
    • A806 Internet
    • A807 Social Networks
    • A9 Fashion / Luxury / Beauty
    • A909 Beauty
    • A911 Fashion and clothes
    • A912 Luxury / Lifestyle
    • A915 Textiles / Footwear
    • B1 Automotive
    • B101 Automotive sports
    • B2 Politics / Economics / Insurance / Law
    • B201 Companies & Businesses
    • B202 Economics
    • B203 Finances
    • B204 Law
    • B205 Politics
    • B206 Work & Employment
    • B207 Wars & Terrorism
    • B208 Public Administration
    • B209 Migrations / Refugees
    • B210 Military and army affairs
    • B211 Insurance
    • B212 European Union

  • Country_path values

    • 00 Undefined
    • 01 Europe
    • 0100 Spain
    • 010001 Catalonia
    • 01000101 Lleida
    • 01000102 Barcelona
    • 01000103 Tarragona
    • 01000104 Girona
    • 01000105 Autonomous
    • 010002 Galicia
    • 01000201 Lugo
    • 01000202 Pontevedra
    • 01000203 Ourense
    • 01000204 La Coruña
    • 01000205 Autonomous
    • 010003 Extremadura
    • 01000301 Cáceres
    • 01000302 Badajoz
    • 01000303 Autonomous
    • 010004 Andalusia
    • 01000401 Huelva
    • 01000402 Seville
    • 01000403 Malaga
    • 01000404 Jaén
    • 01000405 Almería
    • 01000406 Cadiz
    • 01000407 Córdoba
    • 01000408 Granada
    • 01000409 Autonomous
    • 010005 Basque Country
    • 01000501 Álava
    • 01000502 Guipúzcoa
    • 01000503 Vizcaya
    • 01000504 Autonomous
    • 010006 Castile-La Mancha
    • 01000601 Albacete
    • 01000602 Ciudad Real
    • 01000603 Cuenca
    • 01000604 Guadalajara
    • 01000605 Toledo
    • 01000606 Autonomous
    • 010007 Murcia
    • 01000701 Autonomous
    • 010008 Canaries
    • 01000801 Las Palmas
    • 01000802 Santa Cruz de Tenerife
    • 01000803 Autonomous
    • 010009 Ceuta and Melilla
    • 01000901 Autonomous
    • 01000B Autonomous Community of Valencia
    • 01000B01 Alicante
    • 01000B02 Castellón
    • 01000B03 Valencia
    • 01000B04 Autonomous
    • 01000C Autonomous Community of Madrid
    • 01000C01 Autonomous
    • 01000D Principality of Asturias
    • 01000D01 Autonomous
    • 01000E Cantabria
    • 01000E01 Autonomous
    • 01000F Castile and Leon
    • 01000F01 Ávila
    • 01000F02 Burgos
    • 01000F03 León
    • 01000F04 Palencia
    • 01000F05 Salamanca
    • 01000F06 Segovia
    • 01000F07 Soria
    • 01000F08 Valladolid
    • 01000F09 Zamora
    • 01000F0A Autonomous
    • 010010 Navarre
    • 01001001 Autonomous
    • 010011 Aragon
    • 01001101 Huesca
    • 01001102 Teruel
    • 01001103 Zaragoza
    • 01001104 Autonomous
    • 010012 Balearic Islands
    • 01001201 Autonomous
    • 010013 La Rioja
    • 01001301 Autonomous
    • 010014 National
    • 0101 Portugal
    • 0102 Denmark
    • 0103 United Kingdom
    • 0104 Andorra
    • 0105 Belgium
    • 0106 Italy
    • 0107 France
    • 010701 Alsace
    • 010702 Aquitaine
    • 010703 Auvergne
    • 010704 Burgundy
    • 010705 Brittany
    • 010706 Centre
    • 010707 Champagne-Ardenne
    • 010708 Corsica
    • 010709 Franche-Compte
    • 01070A Ile-De-France
    • 01070B Languedoc-Roussillon
    • 01070C Limousin
    • 01070D Lorraine
    • 01070E Midi-Pyrenees
    • 01070F Nord-Pas-de-Calais
    • 010710 Lower Normandy
    • 010711 Upper Normandy
    • 010712 Pays de la Loire
    • 010713 Picardy
    • 010714 Poitou-Charentes
    • 010715 Provence-Alpes-Cote dazur
    • 010716 Rhone-Alpes
    • 010717 Guadaeloupe
    • 010718 French Guiana
    • 010719 Martinique
    • 01071A Mayotte
    • 01071B La Reunion
    • 01071C National
    • 01071D Saint-Pierre and Miquelon
    • 01071E New Caledonia
    • 01071F Wallis and Futuna
    • 010720 French Southern and Antarctic Lands
    • 010721 French Polynesia
    • 010722 Saint Martin
    • 010723 Saint Barthelemy
    • 0108 Albania
    • 0109 Germany
    • 0110 Austria
    • 0111 Belarus
    • 0112 Bosnia-Herzegovina
    • 0113 Bulgaria
    • 0114 Croatia
    • 0115 Cyprus
    • 0116 Slovakia
    • 0117 Slovenia
    • 0118 Estonia
    • 0119 Finland
    • 0120 Greece
    • 0121 Hungary
    • 0122 Ireland
    • 0123 Iceland
    • 0124 Latvia
    • 0125 Liechtenstein
    • 0126 Lithuania
    • 0127 Luxembourg
    • 0128 Macedonia
    • 0129 Malta
    • 0130 Moldova
    • 0131 Monaco
    • 0132 Norway
    • 0133 Netherlands, The
    • 0134 Poland
    • 0135 Czech Republic
    • 0136 Romania
    • 0137 San Marino
    • 0138 Sweden
    • 0139 Switzerland
    • 0140 Turkey
    • 0141 Ukraine
    • 0142 Vatican
    • 0143 Serbia
    • 0145 Isle of Man
    • 0146 Guernsey
    • 0147 Jersey
    • 0148 Montenegro
    • 0149 Georgia
    • 0151 Aland
    • 0152 Faroe Islands
    • 0153 Gibraltar
    • 02 South America
    • 0200 Uruguay
    • 0201 Argentina
    • 0202 Venezuela
    • 0203 Colombia
    • 0204 Ecuador
    • 0205 Chile
    • 0206 Bolivia
    • 0207 Peru
    • 020701 Amazonas
    • 020702 Ancash
    • 020703 Apurímac
    • 020704 Arequipa
    • 020705 Ayacucho
    • 020706 Cajamarca
    • 020707 Callao
    • 020708 Cuzco
    • 020709 Huancavelica
    • 02070A Huánuco
    • 02070B Ica
    • 02070C Junín
    • 02070D La Libertad
    • 02070E Lambayeque
    • 02070F Lima
    • 020710 Loreto
    • 020711 Madre de Dios
    • 020712 Moquegua
    • 020713 Pasco
    • 020714 Piura
    • 020715 Puno
    • 020716 San Martín
    • 020717 Tacna
    • 020718 Tumbes
    • 020719 Ucayali
    • 02071A National
    • 0208 Brazil
    • 0210 Paraguay
    • 0211 Surinam
    • 0212 Guyana
    • 0213 South Georgia & South Sandwich Isl.
    • 0214 Falkland Islands
    • 03 Central America and Caribbean
    • 0300 Mexico
    • 0301 Costa Rica
    • 0302 Panama
    • 0303 Dominican Republic
    • 0304 Belize
    • 0305 Nicaragua
    • 0306 Cuba
    • 0307 Honduras
    • 0308 El Salvador
    • 0309 Puerto Rico
    • 0310 Guatemala
    • 0311 Bahamas
    • 0312 Haiti
    • 0313 Jamaica
    • 0317 Anguilla
    • 0318 Antigua and Barbuda
    • 0319 Aruba
    • 0320 Barbados
    • 0321 Caiman Islands
    • 0322 Dominica
    • 0323 Granada
    • 0326 Montserrat
    • 0327 Netherlands Antilles
    • 0328 San Kitts and Nevis
    • 0329 Saint Lucia
    • 0330 Saint Vincent and the Grenadines
    • 0331 Trinidad and Tobago
    • 0332 Turks and Caicos Islands
    • 0333 United States Minor Outlying Islands
    • 0334 Virgin Islands, British
    • 0335 Virgin Islands, U.S.
    • 04 North America
    • 0400 USA
    • 040001 Alaska
    • 040002 Arizona
    • 040003 Arkansas
    • 040004 California
    • 040005 North Carolina
    • 040006 Colorado
    • 040007 Connecticut
    • 040008 District of Columbia
    • 040009 Florida
    • 04000A Georgia
    • 04000B Illinois
    • 04000C Indiana
    • 04000D Kansas
    • 04000E Maryland
    • 04000F Massachussetts
    • 040010 Michigan
    • 040011 New Jersey
    • 040012 New York
    • 040013 New Mexico
    • 040014 Ohio
    • 040015 Oklahoma
    • 040016 Oregon
    • 040017 Rhode Island
    • 040018 Tennessee
    • 040019 Texas
    • 04001A Utah
    • 04001B Virginia
    • 04001C Washington
    • 04001D Washington, D.C.
    • 04001E Los Angeles
    • 04001F Dallas
    • 040020 Boston
    • 040021 Orlando
    • 040022 National
    • 040023 Alabama
    • 040024 Delaware
    • 040025 Hawaii
    • 040026 Idaho
    • 040027 Iowa
    • 040028 Kentucky
    • 040029 Louisiana
    • 04002A Maine
    • 04002B Minnesota
    • 04002C Mississippi
    • 04002D Missouri
    • 04002E Montana
    • 04002F Nebraska
    • 040030 Nevada
    • 040031 New Hampshire
    • 040032 North Dakota
    • 040033 Pennsylvania
    • 040034 South Carolina
    • 040035 South Dakota
    • 040036 Vermont
    • 040037 West Virginia
    • 040038 Wisconsin
    • 040039 Wyoming
    • 0401 Bermuda
    • 0402 Canada
    • 0403 Greenland
    • 05 Asia
    • 0500 Afghanistan
    • 0501 Saudi Arabia
    • 0502 Armenia
    • 0503 Azerbaijan
    • 0504 Bahrein
    • 0505 Bangladesh
    • 0506 Myanmar
    • 0507 Brunei Darussalam
    • 0508 Bhutan
    • 0509 Cambodia
    • 0510 North Korea
    • 0511 South Korea
    • 0512 China
    • 0513 United Arab Emirates
    • 0514 The Philippines
    • 0515 India
    • 0516 Indonesia
    • 0517 Iraq
    • 0518 Iran
    • 0519 Israel
    • 0520 Japan
    • 0521 Jordan
    • 0522 Kazakhstan
    • 0523 Kirgizistan
    • 0524 Kuwait
    • 0525 Laos
    • 0526 Lebanon
    • 0527 Malaysia
    • 0528 Maldives
    • 0529 Mongolia
    • 0530 Nepal
    • 0531 Oman
    • 0532 Pakistan
    • 0533 Qatar
    • 0534 Russia
    • 0535 Singapore
    • 0536 Syria
    • 0537 Sri Lanka
    • 0538 Thailand
    • 0539 Taiwan
    • 0540 Tadjikistan
    • 0541 Turkmenistan
    • 0542 Uzbekistan
    • 0543 Vietnam
    • 0544 Yemen
    • 0545 British Indian Ocean Territory
    • 0546 Hong Kong
    • 0548 Timor-Leste
    • 0549 Palestinian Territory
    • 0550 Macao
    • 06 Africa
    • 0600 Morocco
    • 0601 Angola
    • 0602 Algeria
    • 0603 Benin
    • 0604 Botswana
    • 0605 Burkina Faso
    • 0606 Burundi
    • 0607 Cape Verde
    • 0608 Cameroon
    • 0609 Comoros
    • 0610 Ivory Coast
    • 0611 Chad
    • 0612 Djibouti
    • 0613 Egypt
    • 0614 Eritrea
    • 0615 Ethiopia
    • 0616 Gabon
    • 0617 The Gambia
    • 0618 Ghana
    • 0619 Guinea
    • 0620 Guinea-Bissau
    • 0621 Equatorial Guinea
    • 0622 Kenya
    • 0623 Lesotho
    • 0624 Liberia
    • 0625 Libya
    • 0626 Madagascar
    • 0627 Malawi
    • 0628 Mali
    • 0629 Mauritius
    • 0631 Mozambique
    • 0632 Namibia
    • 0633 Niger
    • 0634 Nigeria
    • 0635 Central African Republic
    • 0636 Democratic Republic of Congo
    • 0638 Rwanda
    • 0639 Western Sahara
    • 0640 Saint Helena and Dependencies
    • 0641 Sao Tome and Principe
    • 0642 Senegal
    • 0643 Seychelles
    • 0644 Sierra Leone
    • 0645 Somalia
    • 0646 Swaziland
    • 0647 Sudan
    • 0648 South Africa
    • 0649 Tanzania
    • 0650 Togo
    • 0651 Tunisia
    • 0652 Uganda
    • 0653 Zambia
    • 0654 Zimbabwe
    • 0655 Mauritania
    • 07 Oceania
    • 0701 Australia
    • 0702 Fiji
    • 0703 Guam
    • 0706 Marshall Islands
    • 0707 Pitcairn_Island
    • 0708 Solomon_Islands
    • 0709 Kiribati
    • 070A Northern Mariana Islands
    • 070B Micronesia
    • 070C Nauru
    • 070D New Zealand
    • 070E Palau
    • 070F Papua New Guinea
    • 0711 Samoa
    • 0712 American_Samoa
    • 0714 Tokelau
    • 0715 Tonga
    • 0716 Tuvalu
    • 0717 Vanuatu
    • 0719 Christmas Island
    • 0720 Cocos Islands
    • 0721 Cook Islands
    • 0723 Niue
    • 0724 Norfolk Island
    • 08 Antarctica
    • 0800 Antarctica
    • 0801 Bouvet Island
    • 0803 Heard and McDonald Islands
    • 0804 Svalbard and Jan Mayen

Using restricted characters

Restricted characters used in lucene syntax are

(+ - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /)

The way to use these characters is to URL encode and escape them with \

  • Request ?q=”\%22ernest\%26young\%22

    It searches for the phrase “ernest & young”

  • Request ?q=”\%28augure\%29”

    It searches for the term (augure)

  • Request ?q=“augure\%2A”

    It searches for the term augure*

  • Request ?q=“ernest\%26young”

    It searches for the terms earnest & young

Right now, especial characters are not properly tokenized in index.

In the examples we’re searching for “ernest&young” but in the search process what we’re really searching is “ernest young” because “&” is not properly mapped and elastic will omit this character and will put a white space between the two words.

At indexation time right now “ernest&young” is saved in lucene as [“ernest”, “young”].If we need to search for specific special characters like #augureOP and we only need those hashtags and nothing else like tweets with “augureOP”, we will need to change the tokenizer inside index configuration to save [“#augureOP”, augureOP] and not [“augureOP”] only. This scenario is not possible right now and we’ll need to reindex all data.

Documents

Documents
GET/documents{?query,filter,period,begin_date,end_date,sort,start,limit,limit_facets,channel_type_id_filter,topic_paths_filter,language_id_filter,country_path_filter,key_phrases_filter,response_type,debug}

Method used to search publications.

Example URI

GET https://nap.launchmetrics.com/search/v1/documents?query=girona&filter=language_id:1&period=last_week&begin_date=2015-02-15T00:00:00+01:00:00&end_date=&sort=&start=10&limit=2&limit_facets=2&channel_type_id_filter=&topic_paths_filter=&language_id_filter=&country_path_filter=&key_phrases_filter=&response_type=&debug=
URI Parameters
HideShow
query
string (optional) Example: girona

Search query, contains the words we’re searching for (you can use lucene syntax, AND OR NOT). NOT and - are equivalent. + and AND are equivalent.

You can omit query parameter if you specify filters, otherwise is required

filter
string (optional) Example: language_id:1

Filter query to filter by some criteria (you can use lucene syntax).

This filter will be applied to the main query and all aggregations, including facets and stats if enabled.

You should specify the index field to filter (See the available fields section).

Here you cannot specify range dates, use the period, begin_date or end_date instead.

The spaces inside filter will be treated as " AND " operator.

If " OR " operator is needed, must be explicitly added in the filter.

With no OR specified: filter=+topic_paths:(0920 1350) == filter=(topic_path:0920 AND topic_path:1350)

period
string (optional) Default: last_month Example: last_week

String specifying period (ISO8601 format with leading Z for UTC, or UTC offset)

You cannot specify period, begin_date and end_date on the same requests, use one or the other

Choices: last_week last_three_months last_month last_year

begin_date
string (optional) Example: 2015-02-15T00:00:00+01:00:00

Specific begin date

Date format must be ISO8601 with leading Z for UTC, or UTC offset

Some valid dates:

2015-05-03T15:38:45Z 2015-05-03T15:38:45+00:00 2015-05-03T16:38:45+01:00 2015-05-03T14:38:45-01:00

end_date
string (optional) 

Specific end date

sort
string (optional) Default: publication_date:desc 

Comma separated field for sorting Examples:

sort=audicence:asc,id:desc

start
number (optional) Default: 0 Example: 10

Offset to start displaying results

start + limit can’t be greather than 10000

limit
number (optional) Default: 20 Example: 2

Number max of documents to return (max value is 500)

limit_facets
number (optional) Default: 0 Example: 2

Number of facets to return (max value is 500)

channel_type_id_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

topic_paths_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

language_id_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

country_path_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

key_phrases_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

response_type
string (optional) Default: default 

Allow to change results format, the raw format it’s directly the elastic response

Choices: default raw

debug
number (optional) Default: 0 

Returns debugging information like as sent query and the indexes

Request  Search for an specified number of results
HideShow
Headers
Content-Type: sortered
Body
documents?query=girona&limit=5&sort=publication_date%3Adesc
Request  Searching documents from a given signature + some filtering
HideShow
Body
documents?query=signature_id%3A10557170&filter=channel_type_id%3A(0 OR 1 OR 2 OR 3 OR 4 OR 5 OR 12)
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "facets": {
    "language_id": {
      "2": 119061,
      "3": 113521,
      "4": 6277,
      "7": 8808,
      "11": 5679
    },
    "channel_type_id": {
      "0": 188435,
      "5": 11698,
      "12": 7890,
      "30": 50786,
      "51": 4777
    },
    "topic_paths": {
      "07": 42171,
      "09": 50669,
      "0920": 46045,
      "03": 49279,
      "0C": 55330
    },
    "country_path": {
      "0102": 5615,
      "0402": 7407,
      "0400": 66871,
      "0107": 72722,
      "0103": 19981
    }
  },
  "total": 271591,
  "start": 0,
  "documents": [
    "14583408681340609998",
    "14583400211340115141",
    "14583404541363685573",
    "14583399361339582592",
    "14583578871445884509",
    "14583406421339583357",
    "14583989011363685839",
    "14583301021445884509",
    "14583259411339583357",
    "14583259541339582592",
    "14583260731340115141",
    "14583261801363685839",
    "14583245601340609998",
    "14583235811363685573",
    "14593578741147346313",
    "14594193301147346313",
    "14586286521147342817",
    "14586127891147346313",
    "14585890901391599695",
    "14585668081332843806"
  ]
}

Documents
POST/documents{?query,filter,period,begin_date,end_date,sort,start,limit,limit_facets,channel_type_id_filter,topic_paths_filter,language_id_filter,country_path_filter,key_phrases_filter,response_type,debug}

Same as GET but passing parameters in the body

Example URI

POST https://nap.launchmetrics.com/search/v1/documents?query=girona&filter=language_id:1&period=last_week&begin_date=2015-02-15T00:00:00+01:00:00&end_date=&sort=&start=10&limit=2&limit_facets=2&channel_type_id_filter=&topic_paths_filter=&language_id_filter=&country_path_filter=&key_phrases_filter=&response_type=&debug=
URI Parameters
HideShow
query
string (optional) Example: girona

Search query, contains the words we’re searching for (you can use lucene syntax, AND OR NOT). NOT and - are equivalent. + and AND are equivalent.

You can omit query parameter if you specify filters, otherwise is required

filter
string (optional) Example: language_id:1

Filter query to filter by some criteria (you can use lucene syntax).

This filter will be applied to the main query and all aggregations, including facets and stats if enabled.

You should specify the index field to filter (See the available fields section).

Here you cannot specify range dates, use the period, begin_date or end_date instead.

The spaces inside filter will be treated as " AND " operator.

If " OR " operator is needed, must be explicitly added in the filter.

With no OR specified: filter=+topic_paths:(0920 1350) == filter=(topic_path:0920 AND topic_path:1350)

period
string (optional) Default: last_month Example: last_week

String specifying period (ISO8601 format with leading Z for UTC, or UTC offset)

You cannot specify period, begin_date and end_date on the same requests, use one or the other

Choices: last_week last_three_months last_month last_year

begin_date
string (optional) Example: 2015-02-15T00:00:00+01:00:00

Specific begin date

Date format must be ISO8601 with leading Z for UTC, or UTC offset

Some valid dates:

2015-05-03T15:38:45Z 2015-05-03T15:38:45+00:00 2015-05-03T16:38:45+01:00 2015-05-03T14:38:45-01:00

end_date
string (optional) 

Specific end date

sort
string (optional) Default: publication_date:desc 

Comma separated field for sorting Examples:

sort=audicence:asc,id:desc

start
number (optional) Default: 0 Example: 10

Offset to start displaying results

start + limit can’t be greather than 10000

limit
number (optional) Default: 20 Example: 2

Number max of documents to return (max value is 500)

limit_facets
number (optional) Default: 0 Example: 2

Number of facets to return (max value is 500)

channel_type_id_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

topic_paths_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

language_id_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

country_path_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

key_phrases_filter
string (optional) 

Specific filter for this field, only used if no filter parameter. Values separated by comma

response_type
string (optional) Default: default 

Allow to change results format, the raw format it’s directly the elastic response

Choices: default raw

debug
number (optional) Default: 0 

Returns debugging information like as sent query and the indexes

Request  Search for an specified number of results and ordered
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
query=girona&limit=5&sort=publication_date%3Adesc
Request  Searching documents from a given signature + some filtering
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
query=signature_id%3A10557170&filter=channel_type_id%3A(0 OR 1 OR 2 OR 3 OR 4 OR 5 OR 12)
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "facets": {
    "language_id": {
      "2": 119061,
      "3": 113521,
      "4": 6277,
      "7": 8808,
      "11": 5679
    },
    "channel_type_id": {
      "0": 188435,
      "5": 11698,
      "12": 7890,
      "30": 50786,
      "51": 4777
    },
    "topic_paths": {
      "07": 42171,
      "09": 50669,
      "0920": 46045,
      "03": 49279,
      "0C": 55330
    },
    "country_path": {
      "0102": 5615,
      "0402": 7407,
      "0400": 66871,
      "0107": 72722,
      "0103": 19981
    }
  },
  "total": 271591,
  "start": 0,
  "documents": [
    "14583408681340609998",
    "14583400211340115141",
    "14583404541363685573",
    "14583399361339582592",
    "14583578871445884509",
    "14583406421339583357",
    "14583989011363685839",
    "14583301021445884509",
    "14583259411339583357",
    "14583259541339582592",
    "14583260731340115141",
    "14583261801363685839",
    "14583245601340609998",
    "14583235811363685573",
    "14593578741147346313",
    "14594193301147346313",
    "14586286521147342817",
    "14586127891147346313",
    "14585890901391599695",
    "14585668081332843806"
  ]
}

Facet Collection

Documents

Document
GET/documents/facets{?query,filter,period,begin_date,end_date,limit,facet_fields,channel_type_id_filter,topic_paths_filter,language_id_filter,country_path_filter,key_phrases_filter,response_type,debug,aggs}

Method used to do faceting over a documents search.

Example URI

GET https://nap.launchmetrics.com/search/v1/documents/facets?query=girona&filter=language_id:1&period=last_week&begin_date=2015-02-15T00:00:00+01:00:00&end_date=&limit=2&facet_fields=&channel_type_id_filter=&topic_paths_filter=&language_id_filter=&country_path_filter=&key_phrases_filter=&response_type=&debug=&aggs=
URI Parameters
HideShow
query
string (required) Example: girona

Search query, contains the words we’re searching for (you can use lucene syntax, AND OR NOT). NOT and - are equivalent. + and AND are equivalent.

filter
string (optional) Example: language_id:1

Filter query to filter by some criteria (you can use lucene syntax).

This filter will be applied to the main query only.

You should specify the index field to filter (See the available fields section).

Here you cannot specify range dates, use the period, begin_date or end_date instead.

The spaces inside filter will be treated as " AND " operator.

If " OR " operator is needed, must be explicitly added in the filter.

With no OR specified: filter=+topic_paths:(0920 1350) == filter=(topic_path:0920 AND topic_path:1350)

period
string (optional) Default: last_month Example: last_week

String specifying period (ISO8601 format with leading Z for UTC, or UTC offset)

You cannot specify period, begin_date and end_date on the same requests, use one or the other

Choices: last_week last_three_months last_month last_year

begin_date
string (optional) Example: 2015-02-15T00:00:00+01:00:00

Specific begin date

Date format must be ISO8601 with leading Z for UTC, or UTC offset

Some valid dates:

2015-05-03T15:38:45Z 2015-05-03T15:38:45+00:00 2015-05-03T16:38:45+01:00 2015-05-03T14:38:45-01:00

limit
number (optional) Default: 10 Example: 2

Number max of facets to return (max value is 500) (the returned facets will be top ones sorted by hit count).

facet_fields
string (optional) 

A comma separated list of facet fields

Possible values are:

  • channel_type_id

  • topic_paths

  • language_id

  • country_path

  • key_phrases

channel_type_id_filter
string (optional) 

Specific filter for this field. Values separated by comma

topic_paths_filter
string (optional) 

Specific filter for this field. Values separated by comma

language_id_filter
string (optional) 

Specific filter for this field. Values separated by comma

country_path_filter
string (optional) 

Specific filter for this field. Values separated by comma

key_phrases_filter
string (optional) 

Specific filter for this field. Values separated by comma

end_date
string (optional) 

Specific end date

response_type
string (optional) Default: default 

Allow to change results format, the raw format it’s directly the elastic response

Choices: default raw

debug
number (optional) Default: 0 

Returns debugging information like as sent query and the indexes

aggs
text (optional) 

Custom aggregation, add a json with elasticsearch aggregation. You must remove the first “aggs” that’s normally required by elasticsearch. (POST recommended 😃) This parameter will disable faceting.

Request  Default facet query that returns the top 5 facets
HideShow
Body
documents/facets?query=girona&limit=5
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "total_hits": 792543,
  "facets": {
    "topic_paths": {
      "030C": 104139,
      "0304": 107943,
      "1D": 393319,
      "1D08": 387420,
      "03": 194054
    },
    "channel_type_id": {
      "0": 657435,
      "2": 6055,
      "5": 25423,
      "12": 62737,
      "30": 33407
    },
    "language_id": {
      "0": 391,
      "2": 1778,
      "3": 34661,
      "4": 8,
      "7": 22
    },
    "country_path": {
      "0103": 33097,
      "0400": 229211,
      "0107": 36869,
      "0100": 39619,
      "0106": 41792
    }
  }
}

Document
POST/documents/facets{?query,filter,period,begin_date,end_date,limit,debug}

Method used to do faceting over a documents search, it’s only usable for those petitions with custom aggregations.

In body , add a json with elasticsearch aggregation. You must remove the first “aggs” that’s normally required by elasticsearch.

This action will not make any faceting, will only execute custom aggregations.

Example URI

POST https://nap.launchmetrics.com/search/v1/documents/facets?query=girona&filter=language_id:1&period=last_week&begin_date=2015-02-15T00:00:00+01:00:00&end_date=&limit=2&debug=
URI Parameters
HideShow
query
string (required) Example: girona

Search query, contains the words we’re searching for (you can use lucene syntax, AND OR NOT). NOT and - are equivalent. + and AND are equivalent.

filter
string (optional) Example: language_id:1

Filter query to filter by some criteria (you can use lucene syntax).

This filter will be applied to the main query only.

You should specify the index field to filter (See the available fields section).

Here you cannot specify range dates, use the period, begin_date or end_date instead.

The spaces inside filter will be treated as " AND " operator.

If " OR " operator is needed, must be explicitly added in the filter.

With no OR specified: filter=+topic_paths:(0920 1350) == filter=(topic_path:0920 AND topic_path:1350)

period
string (optional) Default: last_month Example: last_week

String specifying period (ISO8601 format with leading Z for UTC, or UTC offset)

You cannot specify period, begin_date and end_date on the same requests, use one or the other

Choices: last_week last_three_months last_month last_year

begin_date
string (optional) Example: 2015-02-15T00:00:00+01:00:00

Specific begin date

Date format must be ISO8601 with leading Z for UTC, or UTC offset

Some valid dates:

2015-05-03T15:38:45Z 2015-05-03T15:38:45+00:00 2015-05-03T16:38:45+01:00 2015-05-03T14:38:45-01:00

limit
number (optional) Default: 10 Example: 2

Number max of facets to return (max value is 500) (the returned facets will be top ones sorted by hit count).

end_date
string (optional) 

Specific end date

debug
number (optional) Default: 0 

Returns debugging information like as sent query and the indexes

Request
HideShow
Headers
Content-Type: text/json
Body
{
  "date_histogram": {
    "field": "publication_date",
    "interval": "day"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "request": {
    "parameters": {
      "period": "last_week",
      "filter": "language_id:1",
      "query": "girona"
    },
    "body_json": {
      "date_histogram": {
        "interval": "day",
        "field": "publication_date"
      }
    },
    "method": "POST",
    "path": "/search/v0/documents/facets"
  },
  "response": {
    "raw_response": {
      "aggregations": {
        "customAgg": {
          "buckets": [
            {
              "doc_count": 213,
              "key_as_string": "2017-05-12T00:00:00.000Z",
              "key": 1494547200000
            },
            {
              "doc_count": 272,
              "key_as_string": "2017-05-13T00:00:00.000Z",
              "key": 1494633600000
            },
            {
              "doc_count": 162,
              "key_as_string": "2017-05-14T00:00:00.000Z",
              "key": 1494720000000
            },
            {
              "doc_count": 104,
              "key_as_string": "2017-05-15T00:00:00.000Z",
              "key": 1494806400000
            },
            {
              "doc_count": 108,
              "key_as_string": "2017-05-16T00:00:00.000Z",
              "key": 1494892800000
            },
            {
              "doc_count": 173,
              "key_as_string": "2017-05-17T00:00:00.000Z",
              "key": 1494979200000
            },
            {
              "doc_count": 213,
              "key_as_string": "2017-05-18T00:00:00.000Z",
              "key": 1495065600000
            }
          ]
        }
      },
      "hits": {
        "hits": [
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947234051445870309",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947219701445870274",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947219221445870284",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947219201445870280",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947217461445870277",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947233601445870316",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947233621445870315",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947233691445870295",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947232151445870296",
            "_type": "document"
          },
          {
            "_score": 30.687185,
            "_index": "documents_201705",
            "_id": "14947233291445870305",
            "_type": "document"
          }
        ],
        "max_score": 30.687185,
        "total": 1245
      },
      "timed_out": false,
      "_shards": {
        "failed": 0,
        "successful": 5,
        "total": 5
      },
      "took": 4
    }
  },
  "time": "0.594728",
  "status": 200
}

Example use cases

Basic word/phrase searches

The “basic” searches could be done specifying the query parameter:

  • Request ?query=augure

    Returns documents containing “augure”

  • Request ?query=augure wisemetrics

    Returns documents containing augure and/or wisemetrics

  • Request ?query=”augure acquires wisemetrics”

    Returns documents having the given exact match

Documents from one media

We can search documents from a given media, for example:

  • Request ?q=media_id:1284019702

    Returns results from this medias

  • Request ?q=media_id: (1284019702 OR 1002704705)

    Returns results from these medias

  • Request ?q=media_id:1284019702 AND augure

    Returns results from this medias containing augure

  • Request ?q=media_id: (1284019702 OR 1002704705) AND augure

    Returns results from these medias containing augure

Filtering query

Sometimes we want to filter documents by some criteria. It could be done using the filter parameter, using lucene syntax and specifying the field criteria. See the available field section to know the fields that can be used.

  • Request ?q=augure&filter=language_id:3

    Returns results containing augure in french

  • Request ?q=augure&filter=language_id:3 channel_type_id:0

    Returns results containing augure in french from online medias

  • Request ?q=augure&filter=language_id:3 channel_type_id: (1 OR 30)

    Returns results containing augure in french from online medias or twitter

Using date ranges

Filtering results by date could be done using the period or begin_date and end_date parameters.

  • period: It allows you to specify some of our predefined date ranges, the accepted values are:
last_week
last_month
last_three_months
last_year
  • begin_date and end_date: You can specify your own date ranges.

Date format must be ISO8601 with leading Z for UTC, or UTC offset

Some valid dates:

2015-05-03T15:38:45Z
2015-05-03T15:38:45+00:00
2015-05-03T16:38:45+01:00
2015-05-03T14:38:45-01:00

  • Request ?q=augure&period=last_three_months

    Returns results containing augure from last threee months

  • Request ?q=augure&period=last_three_months&filter=language_id:3

    Returns results containining augure from last threee months in french

  • Request ?q=augure&begin_date=2015-05-03T15:38:45Z&end_date=2015-05-20T18:22:00Z

    Returns results containining augure from the specified period

  • Request ?q=augure&begin_date=2015-05-03T15:38:45Z&end_date=2015-05-20T18:22:00Z&filter=language_id:3

    Returns results containining augure from the specified period in french

Generated by aglio on 24 Aug 2026